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About This Book 



This book accompanies the SOMobjects Base Toolkit, which consists of the base (or core) capabilities in the System Object Model 
(SOM) of the SOMobjects Developer Toolkit. The base system is a rich subset of the full-capability SOMobjects Developer Toolkit. 
Because the current manual is a subset of chapters from the full SOMobjects Deve/oper Too/kit Users Guic/e, references herein to the 
"SOMobjects Developer Toolkit" should be interpreted as capabilities of the SOMobjects Base Toolkit. 

This manual explains how programmers using C, C++, and other languages can: 

• Implement class libraries that exploit the SOM library-packaging technology, 

• Develop client programs that use class libraries that were built using SOM, and 

• Develop applications that use the frameworks supplied with the SOMobjects Toolkit, class libraries that facilitate development of 
object-oriented applications. 

In addition to this book, refer to the System Object Mode/ Programming Reference during application development for specific information 
about the classes, methods, functions, and macros supplied with the SOMobjects Toolkit. 

For purchasers of the full-capability SOMobjects systems, the SOMobjects Deve/oper Too/kit: Emitter Framework Guide and Reference 
contains documentation of the Emitter Framework of the SOMobjects Developer Toolkit. In addition, the SOMobjects Deve/oper Too/kit: 
Co/tection C/asses Reference Manuai describes the collection classes and methods provided with the SOMobjects Developer Toolkit. 



How This Book Is Organized 



This book is a subset of the SOMobjects Deve/oper Too/kit Users Guide for the full-capability SOMobjects Developer Toolkit. The omitted 
chapters describe capabilities not included with the SOMobjects Base Toolkit. Chapters that are included appear in their entirety, as written 
for the full-capability SOMobjects systems, except for some references to capabilities not included in the SOMobjects Base Toolkit. 

• Introducing the SOMobjects Developer Toolkit provides an overview of the major elements of SOM. 

• Tutorial for Implementing SOM Classes contains a Tutorial with five evolutionary examples that illustrate techniques for 
implementing classes in SOM. All readers should cover this tutorial. 

• Using SOM Classes in Client Programs describes how an application program creates instances of a SOM class, how it invokes 
methods, and so on. For readers interested only in using SOM classes, rather than building them, chapters 2 and 3 may provide 
all of the information they need to begin using SOM classes. 

■ SOM IDL and the SOM Compiler contains explanations and examples for all valid SOM IDL syntax components, it then presents 
the SOM Compiler, including all compiler options and related environment variables. All class implementors will need to 
reference this chapter. 

• Implementing Classes in SOM provides more comprehensive information about the SOM system itself, including operation of the 
SOM run-time environment, inheritance, and method resolution. This chapter also describes how to create language-neutral 
class libraries using SOM. In addition, it contains some advanced topics for customizing SOM to better suit the needs of a 
particular application. All class implementors will need to reference this chapter. 

• Distributed SOM (DSOM) describes Distributed SOM and how to use it to access objects across address spaces, even on 
different machines. This chapter also describes how to customize DSOM. Note that SOMobjects Base Toolkit supports only 
Workstation DSOM (distribution among processes on a single machine), whereas SOMobjects Developer Toolkit also supports 
Workgroup DSOM (distribution among a network of machines). 

• SOM Interface Repository Framework describes the Interface Repository Framework of classes supplied with the SOMobjects 
Toolkit. 

• Metaclass Framework describes the Metaclass Framework and some utility metaclasses that SOM provides to assist users in 
deriving new classes with special abilities to execute "before" and "after” operations when a method call occurs, as well as other 
capabilities for modifying the default semantics of method invocation and object creation. 

• Event Management Framework describes the Event Manager Framework, which allows grouping of all application events and 
waiting on multiple events in one place. The Event Manager is used by DSOM. 

• SOMobjects Error Codes contains lists of the error codes and messages that can be issued by the SOM kernel or by the various 
frameworks. 



SOM IDL Language Grammar contains the SOM IDL language grammar. 

Implementing Sockets Subclasses describes how to subclass a "Sockets” class that facilitates inter-process communications 
required by the DSOM, Replication, and Event Management Frameworks. 

A glossary and an index conclude this programming guide. 



Who Should Read This Book 



This book is for the professional programmer using C, C++, or another language who wishes to 

• Use SOM to build object-oriented class libraries, or 

• Write application programs using class libraries that others have implemented using SOM, 
even if the programming language does not directly support object-oriented programming. 

The discussions in this book are expressed in the commonly used terminology of object-oriented programming. A number of important terms 
are everyday English words that take on specialized meanings. These terms appear in the Glossary at the back of this book. You may find it 
worth consulting the Glossary if the unusual significance attached to an otherwise ordinary word puzzles you. 

This book assumes that you are an experienced programmer and that you have a general familiarity with the basic notions of object-oriented 
programming. Practical experience using an object-oriented programming language is helpful, but not essential. 

If you would like a good introduction to object-oriented programming or a general survey of the many aspects of the topic, you might enjoy 
reading one of the following books: 

• Booch, G, Object-Oriented Design with App//cat/ons , Benjamin/Cummings 1991, ISBN 0-8053-0091-0. 

• Budd, T, An Introduction to Object-Oriented Programming , Addison-Wesley 1991, ISBN 0-201 -54709-0. 

• Cox, B, and Novobilski, A, Object-Oriented Programming, An Evo/utionary Approach 2nd Edition, Addison-Wesley 1991, ISBN 
0-201-54834-8. 



Introducing the SOMobjects Developer Toolkit 



This section contains: 

• Background information 

• An overview of the SOMobjects Toolkit 

• What's New in SOMobjects Version 2.1 



Background 



Object-oriented programming (or OOP) is an important new programming technology that offers expanded opportunities for software 
reuse and extensibility. Object-oriented programming shifts the emphasis of software development away from functional decomposition and 
toward the recognition of units (called objects) that encapsulate both code and data. As a result, programs become easier to maintain and 
enhance. Object-oriented programs are typically more impervious to the "ripple effects" of subsequent design changes than their 
non-object-oriented counterparts. This, in turn, leads to improvements in programmer productivity. 

Despite its promise, penetration of object-oriented technology to major commercial software products has progressed slowly because of 
certain obstacles. This is particularly true of products that offer only a binary programming interface to their internal object classes (Example: 
products that do not allow access to source code). 



The first obstacle that developers must confront is the choice of an object-oriented programming language. 

So-called"pure" object-oriented language (such as Smalltalk) presume a complete run-time environment (sometimes known as a virtual 
machine), because their semantics represent a major departure from traditional, procedure-oriented system architectures. So long as the 
developer works within the supplied environment, everything works smoothly and consistently. When the need arises to interact with foreign 
environment, however (for example, to make an external procedure call), the pure-object paradigm ends, and objects must be reduced to 
data structures for external manipulation. Unfortunately, data structures do not retain the advantage that objects offer with regard to 
encapsulation and code reuse. 

"Hybrid" languages such as C++(**) on the other hand, require less run-time support, but sometimes result in tight bindings between 
programs that implement objects (called "class libraries") and their clients (the programs that use them). That is, implementation detail is 
often unavoidably compiled into the client programs. Tight binding between class libraries and their clients means that client programs often 
must be recompiled whenever simple changes are made in the library. Furthermore, no binary standard exists for C++ objects, so the C++ 
class libraries produced by one C++ compiler cannot (in general) be used from C++ programs built with a different C++ compiler. 

The second obstacle developers of object-oriented software must confront is that, because different object-oriented languages and toolkits 
embrace incompatible models of what objects are and how they work, software developed using a particular language or toolkit is naturally 
limited in scope. Classes implemented in one language cannot be readily used from another. A C++ programmer, for example, cannot easily 
use classes developed in Smalltalk, nor can a Smalltalk programmer make effective use of C++ classes. Object-oriented language and 
toolkit boundaries become, in effect, barriers to interoperability. 

Ironically, no such barrier exists for ordinary procedure libraries. Software developers routinely construct procedure libraries that can be 
shared across a variety of languages, by adhering to standard linkage conventions. Object-oriented class libraries are inherently different in 
that no binary standards or conventions exist to derive a new class from an existing one, or even to invoke a method in a standard way. 
Procedure libraries also have the benefit that their implementations can be freely changed without requiring client programs to be 
recompiled, unlike the situation for C++ class libraries. 

For developers who need to provide binary class libraries, these are serious obstacles. In an era of open systems and heterogeneous 
networking, a single-language solution is frequently not broad enough. Certainly, mandating a specific compiler from a specific vendor in 
order to use a class library might be grounds not to include the class library with an operating system or other general-purpose product. 

The System Object Model (SOM) is IBM's solution to these problems. 



An Overview of SOM and the SOMobjects Toolkit 



The System Object Model (SOM) is a new object-oriented programming technology for building, packaging, and manipulating binary class 
libraries. 

• With SOM, class implementers describe the interface for a class of objects (names of the methods it supports, the return types, 
parameter types, and so forth) in a standard language called the Interface Definition Language, or IDL. 

■ They then implement methods in their preferred programming language (which may be either an object-oriented programming 
language or a procedural language such as C). 

This means that programmers can begin using SOM quickly, and also extends the advantages of OOP to programmers who use 
non-object-oriented programming languages. 

A principal benefit of using SOM is that SOM accommodates changes in implementation details and even in certain facets of a class ' 
interface, without breaking the binary interface to a class library and without requiring recompilation of client programs. As a rule of thumb , it 
changes to a SOM class do not require source-code changes in client programs, then those client programs will not need to be recompiled. 
This is not true of many object-oriented languages, and it is one of the chief benefits of using SOM. For instance, SOM classes can undergo 
structural changes such as the following, yet retain full backward, binary compatibility: 

■ Adding new methods, 

• Changing the size of an object by adding or deleting instance variables, 

• Inserting new parent (base) classes above a class in the inheritance hierarchy, and 

• Relocating methods upward in the class hierarchy. 

In short, implementers can make the typical kinds of changes to an implementation and its interfaces that evolving software systems 
experience over time. 

Unlike the object models found in formal object-oriented programming languages, SOM is language-neutral. It preserves the key OOP 
characteristics of encapsulation, inheritance, and polymorphism, without requiring that the user of a SOM class and the implementer of a 
SOM class use the same programming language. SOM is said to be language-neutral for four reasons: 



1 . 



All SOM interactions consist of standard procedure calls. On systems that have a standard linkage convention for system calls, 
SOM interactions conform to those conventions. Thus, most programming languages that can make external procedure calls can 
use SOM. 

2. The form of the SOM Application Programming Interface, or API (the way that programmers invoke methods, create objects, and 
so on) can vary widely from language to language, as a benefit of the SOM bindings. Bindings are a set of macros and 
procedure calls that make implementing and using SOM classes more convenient by tailoring the interface to a particular 
programming language. 

3. SOM supports several mechanisms for method resolution that can be readily mapped into the semantics of a wide range of 
object-oriented programming languages. Thus, SOM class libraries can be shared across object-oriented languages that have 
differing object models. A SOM object can potentially be accessed with three different forms of method resolution: 

• Offset resolution: rouahlv equivalent to the C++ "virtual function" concept. Offset resolution implies a static scheme 
for typing objects, with polymorphism based strictly on class derivation. It offers the best performance characteristics 
for SOM method resolution. Methods accessible through offset resolution are called static methods, because they are 
considered a fixed aspect of an object's interface. 

• Name-lookup resolution: similar to that employed by Objective-C and Smalltalk. Name resolution supports untyped 
(sometimes called "dynamically" typed) access to objects, with polymorphism based on the actual protocols that 
objects honor. Name resolution offers the opportunity to write code to manipulate objects with little or no awareness 
of the type or shape of the object when the code is compiled. 

• Dispatch-function resolution : a unique feature of SOM that permits method resolution based on arbitrary rules known 
only in the domain of the receiving object. Languages that require special entry or exit sequences or local objects that 
represent distributed object domains are good candidates for using dispatch-function resolution. This technique offers 
the highest degree of encapsulation for the implementation of an object, with some cost in performance. 

4. SOM conforms fully with the Object Management Group's (OMG) [ OMG is an industry consortium founded to advance the use 
of object technology in distributed, heterogeneous environments] Common Object Request Broker Architecture (CORBA) 
standards. In particular, 

• Interface to SOM classes are described in CORBA's Interface Definition Language, IDL, and the entire SOMobjects 
Toolkit supports all CORBA-defined data types. 

• The SOM bindings for the C language are compatible with the C bindings prescribed by CORBA. 

• All information about the interface to a SOM class is available at run time through a CORBA-defined "Interface 
Repository.” 

SOM is not intended to replace existing object-oriented languages. Rather, it is intended to complement them so that application programs 
written in different programming languages can share common SOM class libraries. For example, SOM can be used with C++ to do the 
following: 



• Provide upwardly compatible class libraries, so that when a new version of a SOM class is released, client code needn't be 
recompiled, so long as no changes to the client's source code are required. 

• Allow other language users (and other C++ compiler users) to use SOM classes implemented in C++. 

• Allow C++ programs to use SOM classes implemented using other languages. 

• Allow other language users to implement SOM classes derived from SOM classes implemented in C++. 

• Allow C++ programmers to implement SOM classes derived from SOM classes implemented using other languages. 

• Allow encapsulation (implementation hiding) so that SOM class libraries can be shared without exposing private instance 

variables and methods. 

• Allow dynamic (run-time) method resolution in addition to static (compile-time) method resolution (on SOM objects). 

• Allow information about classes to be obtained and updated at run time. (C++ classes are compile-time structures that have no 
properties at run time.) 



The SOM Compiler 



The SOMobjects Toolkit contains a tool, called the SOM Compiler, that helps implementers build classes in which interface and 




implementation are decoupled . The SOM Compiler reads the IDL definition of a class interface and generates: 

• an implementation skeleton for the class, 

• bindings for implemented, and 

• bindings for client programs. 

Bindings are language-specific macros and procedures that make implementing and using SOM classes more convenient. These bindings 
offer a convenient interface to SOM that is tailored to a particular programming language. For instance, C programmers can invoke methods 
in the same way they make ordinary procedure calls. The C++ bindings "wrap" SOM objects as C++ objects, so that C++ programmers can 
invoke methods on SOM objects in the same way they invoke methods on C++ objects. In addition, SOM objects receive full C++ 
typechecking, just as C++ objects do. Currently, the SOM Compiler can generate both C and C++ language bindings for a class. The C and 
C++ bindings will work with a variety of commercial products available from IBM and others. Vendors of other programming languages may 
also offer SOM bindings. Check with your language vendor about possible SOM support. 



The SOM run-time library 



In addition to the SOM Compiler, SOM includes a run-time library. This library provides, among other things, a set of classes, methods, 
and procedures used to create object and invoke methods on them. The library allows any programming language to use SOM classes 
(classes developed using SOM) if that language can: 

• Call external procedures, 

• Store a pointer to a procedure and subsequently invoke that procedure, and 

• Map IDL types onto the programming language's native types. 

Thus, the user of a SOM class and the implementer of a SOM class needn't use the same programming language, and neither is required to 
use an object-oriented language. The independence of client language and implementation language also extends to subclassing: a SOM 
class can be derived from other SOM classes, and the subclass may or may not be implemented in the same language as the parent 
class(es). Moreover, SOM's run-time environment allows applications to access information about classes dynamically (at run time). 



Frameworks provided in the SOMobjects Toolkit 



In addition to SOM itself (the SOM compiler and the SOM run-time library), the SOMobjects Developer Toolkit also provides a set of 
frameworks (class libraries) that can be used in developing object-oriented applications. These include Distributed SOM, the Interface 
Repository Framework, and the Emitter Framework, and the Metaclass Framework, described below. 

Note: SOMobjects Base Toolkit, the core version of SOMobject shipped with this documentation, contains only Distributed SOM, the 

Interface Repository, and the Metaclass frameworks. The complete SOMobjects Developer Toolkit can be ordered from IBM by calling 
1 -800-342-6672 in the U.S. or 1 -800-465-7999 in Canada. The part number is 1 0FI9767 for the CD-ROM containing SOMobjects for 
the AIX, OS/2, and Windows platforms (including online documentation). SOMobjects manuals are available individually. 



Distributed SOM 



Distributed SOM (or DSOM) allows application programs to access SOM objects across address spaces. . That is, application programs 
can access objects in other processes, even on different machines. DSOM provides this transparent access to remote objects through its 
Object Request Broker (ORB): the location and implementation of the object are hidden from the client, and the client accesses the object as 
if local. The current release of DSOM supports distribution of objects among processes within a workstation, and across a local area network 
consisting of OS/2 system, AIX systems, or a mix of both. Future releases may support larger enterprise-wide networks. 



Interface Repository Framework 




The Interface Repository is a database, optionally created and maintained by the SOM Compiler, that holds all the information contained in 
the IDL description of a class of objects. The Interface Repository Framework consists of the 1 1 classes defined in the CORBA standard 
for accessing the Interface Repository. Thus, the interface Repository Framework provides run-time access to all information contained in 
the IDL description of a class of objects. Type information is available as TypeCodes - a CORBA-defined way of encoding the complete 
description of any data type that can be constructed in IDL. 



Metaclass Framework 



Finally, the Metaclass Framework is a collection of SOM metaclasses that provide functionality that may be useful to SOM class designers 
for modifying the default semantics of method invocation and object creation. These metaclasses are described in Chapter 8, 'The 
Metaclass Framework." 



What's New in SOMobjects Version 2.1 



Version 2.1 of the SOMobjects Developer Toolkit provides enhanced capabilities and improved performance for both SOM and DSOM. In 
addition, the Toolkit now includes support for DirectToSOM (DTS) C++ compilers. New metaclasses in the Metaclass Framework allow class 
implementors to define classes that automatically possess certain convenience facilities. Also, TCP/IP support is available for Windows 
users, and OS/2 users can choose 32-bit TCP/IP. 

In particular, SOMobjects Version 2.1 offers the following additions over Version 2.0: 



General enhancements 



C++ programmers can use DirectToSOM (DTS) C++ compilers (available from independent software vendors) as an alternative 
to the SOMobjects Toolkit's C++ bindings. (A DTS C++ compiler uses SOM classes to implement C++ objects.) The support 
provided by SOMobjects for DTS C++ consists of various enhancements to the SOM API (useful to SOM programmers in 
general), and a new emitter that produces DTS C++ header files corresponding to SOM IDL. DTS C++ programs include these 
".hh" header files, which are emitted as described under "Generating binding files" in Chapter 4, "SOM IDL and the SOM 
Compiler.” 

With this release, TCP/IP support is now available for SOMobjects For Windows. Also, for OS/2 users only, SOMobjects now 
supports the 32-bit TCP/IP version 2.0, which offers greater performance over the 1 6-bit TCP/IP version 1.2.1. These are 
described in your SOMobjects Installation/Configuration Guide. 

SOMobjects enhancements 

A new default process whereby SOMobjects initializes and destroys objects more efficiently (using the somDefaultlnit and 
somDestruct methods). See "Initializing and Uninitializing Objects" in Chapter 5, "Implementing Classes in SOM." 

A new kind of method, nonstatic, that is similar to a C++ nonstatic member function. It is normally invoked using offset 
resolution but can use any form of SOMobjects method resolution. See "The four kinds of SOM methods” in Chapter 5, 
"Implementing Classes in SOM" and the nonstatic modifier under "Modifier statements" in Chapter 4, "SOM IDL and the SOM 
Compiler.” 

A new kind of data, staticdata, that is similar to C++ static data members. A staticdata variable is not stored in an object; rather, 
the ClassData structure of the implementing class contains a pointer to the variable. See the staticdatamodifier under "Modifier 
statements" in Chapter 4, "SOM IDL and the SOM Compiler." 

Two new modifiers, somallocate and somdeallocate, used to indicate that a user-written procedure should be executed to 
allocate/deallocate memory for class instances when the somAllocate or somDeallocate method is invoked. See these 
modifiers under "Modifier statements” in Chapter 4, "SOM IDL and the SOM Compiler." 



The ability to "cast" objects. See the methods somCastObj and somResetObj. 




• New support for loading/unloading class libraries. (This was introduced in SOMobjects For Windows and is now applicable on 
OS/2 as well.) See the SOM_ClassLibrary macro in the SOMobjects Base Toolkit Programmers Reference Manual. 

DSOM enhancements 

• A new command-line tool, dsom, for managing DSOM servers (starting, restarting, stopping, querying, and so forth). See "The 
dsom server manager utility” in Chapter 6, "Distributed SOM." In addition, a corresponding programmatic interface is provided 
by methods of the new SOMDServerMgr class. See that class and its methods in the SOMobjects Base Toolkit Programmers 
Reference Manual. 

• A new command-line tool, somdchk, that performs environment validation. See "Verifying the DSOM environment with 
somdchk" in Chapter 6, "Distribute SOM." 

• New SOM IDL modifiers for memory management of parameters: memory_management= corba, caller_owns_parameters, 
caller_owns_result, object_owns_parameters, and object_owns_result. The individual modifiers are described under 
"Modifier statements” in Chapter 4, "SOM IDL and the SOM Compiler." See "Memory management" in Chapter 6, "Distributed 
SOM," for a complete discussion of the subject. This memory-management support also includes the new method 
somdReleaseResources and the functions somdExceptionFree and SOMDNoORBfree, described in the SOMobject Base 
Too/k/t Programmers Reference Manual. 

• A graphical user interface to the DSOM 'regimpl' utility on OS/2, called pregimpl. See "Registration steps using 'pregimpl' or 
'wregimpl', " in Chapter 6, "Distributed SOM." 

• Support for the CORBA constant OBJECT_NIL. In addition, the is_nil method of SOMDObject can now be used for local objects 
as well as NULL pointers. 

• Support for passing self-referential structs and unions (those valid in IDL) in remote method calls. 

• Support for local/remote transparency in DSOM's object-destruction methods. See "Destroying remote objects." 

• Ability for users to define customized base proxy classes. See "Customizing the default base proxy class." 

• Ability for users to specify an upper limit on the number of threads that a server can spawn, via the SOMDNUMTFIREADS 
environment variable. See this variable under "Preparing the environment." 

• Improved error handling and performance improvements. 

• More sample programs distributed with the SOMobjects Toolkit. 

Metaclass Framework 

• SOMMBeforeAfter - a metaclass that enables the programming of "before/after" metaclasses, whose instances execute a 
particular method before and after each method invocation. See Chapter 8, "The Metaclass Framework," for information about 
the new Metaclass Framework. Individual metaclasses, along with related classes and methods, are documented in the 
SOMobjects Base Toolkit Programmers Reference Manual. 

• SOMMTraced- a utility metaclass to do tracing. 



New restrictions and deprecated methods 



While implementing the Metaclass Framework, IBM learned that metaclasses must be programmed so that the capabilities they implement 
will be preserved when various metaclasses are combined (using multiple inheritance) into a SOM-derived metaclass. To assure this result, 
the Metaclass Framework metaclasses have been programmed using a "Cooperative Metaclass." Flowever, IBM is not yet ready to include 
the Cooperative metaclass among the officially supported features of SOMobjects. 

To prevent user-defined metaclasses from interfering with the operation of the Cooperative Metaclass and consequently with the Metaclass 
Framework, SOMobjects programmers are strongly urged to observe the following restriction when programming new metaclasses: 

• User-defined metaclasses can introduce new class methods and class variables, but should not override any of the methods 
introduced by the SOMCIass class. 

SOMobjects users whose metaclass programming requirements cannot be met within the above restrictions will be given access to the 
Cooperative Metaclass and its documentation. Note, however, that metaclasses developed using the Cooperative Metaclass may require 
reprogramming when an officially supported Cooperative Metaclass is later introduced. 



In addition, use of a number of (public) methods introduced by SOMCIass is now deprecated because they are useful only from overridden 




SOMCIass methods. These methods are listed under the heading "Deprecated methods" in the documentation for SOMCIass within the 
SOMobjects Base Toolkit Programmers Reference Manual, until such time as SOMobjects is ready to officially provide a framework within 
which their use will not interfere with the internal operation of SOMobjects itself. 



Tutorial for Implementing SOM Classes 



This tutorial contains five examples showing how SOM classes can be implemented to achieve various functionality. Obviously, for any 
person who wishes to become a class implementor, this tutorial is essential. However, even for those programmers who expect only to use 
SOM classes that were implemented by others, the tutorial is also necessary, as it presents several concepts that will help clarify the 
process of using SOM classes. 



Basic Concepts of the System Object Model (SOM) 



The System Object Model (SOM), provided by the SOMobjects Developer Toolkit, is a set of libraries, utilities, and conventions used to 
create binary class libraries that can be used by application programs written in various object-oriented programming languages, such as 
C++ and Smalltalk, or in traditional procedural languages, such as C and Cobol. The following paragraphs introduce some of the basic 
terminology used when creating classes in SOM: 

• An object is an OOP entity that has behavior (its methods or operations) and state (its data values). In SOM, an object is a 
run-time entity with a specific set of methods and instance variables. The methods are used by a client programmer to make the 
object exhibit behavior (that is, to do something), and the instance variables are used by the object to store its state. (The state 
of an object can change over time, which allows the object's behavior to change.) When a method is invoked on an object, the 
object is said to be the receiver or target of the method call. 

• An object's imp/ementat/on is determined by the procedures that execute its methods, and by the type and layout of its instance 
variables. The procedures and instance variables that implement an object are normally encapsulated (hidden from the caller), 
so a program can use the object's methods without knowing anything about how those methods are implemented. Instead, a 
user is given access to the object’s methods through its interface (a description of the methods in terms of the data elements 
required as input and the type of value each method returns). 

• An interface through which an object may be manipulated is represented by an object type. That is, by declaring a type for an 
object variable, a programmer specifies the interface that is intended to be used to access that object. SOM /DL (the SOM 
Interface Definition Language) is used to define object interfaces. The interface names used in these IDL definitions are also 
the type names used by programmers when typing SOM object variables. 

• In SOM, as in most approaches to object-oriented programming, a c/ass defines the implementation of objects. That is, the 
implementation of any SOM object (as well as its interface) is defined by some specific SOM class. A class definition begins with 
an IDL specification of the interface to its objects, and the name of this interface is used as the class name as well. Each object 
of a given class may also be called an instance of the class, or an instantiation of the class. 

• inheritance, or c/ass derivation , is a technique for developing new classes from existing classes. The original class is called the 
base class, or the parent class, or sometimes the direct ancestor class. The derived class is called a chi/d class or a subc/ass. 
The primary advantage of inheritance is that a derived class inherits all of its parent's methods and instance variables. Also 
through inheritance, a new class can override (or redefine) methods of its parent, in order to provide enhanced functionality as 
needed. In addition, a derived class can introduce new methods of its own. If a class results from several generations of 
successive class derivation, that class "knows" all of its ancestors's methods (whether overridden or not), and an object (or 
instance) of that class can execute any of those methods. 

• SOM classes can also take advantage of mu/tip/e inheritance, which means that a new class is jointly derived from two or more 
parent classes. In this case, the derived class inherits methods from all of its parents (and all of its ancestors), giving it greatly 
expanded capabilities. In the event that different parents have methods of the same name that execute differently, SOM provides 
ways for avoiding conflicts. 

• In the SOM run time, classes are themselves objects. That is, classes have their own methods and interfaces, and are 
themselves defined by other classes. For this reason, a class is often called a c/ass object. Likewise, the terms c/ass methods 
and c/ass variab/es are used to distinguish between the methods/variables of a class object vs. those of its instances. (Note 
that the type of an object is not the same as the type of its class, which as a "class object" has its own type.) 

• A class that defines the implementation of class objects is called a metac/ass . Just as an instance of a class is an object, so an 
instance of a metaclass is a class object. Moreover, just as an ordinary class defines methods that its objects respond to, so a 
metaclass defines methods that a class object responds to. For example, such methods might involve operations that execute 
when a class (that is, a class object) is creating an instance of itself (an object). Just as classes are derived from parent classes, 




so metaclasses can be derived from parent metaclasses, in order to define new functionality for class objects. 

• The SOM system contains three primitive classes that are the basis for all subsequent classes: 

SOMObject the root ancestor class for all SOM classes, 

SOMCIass the root ancestor class for all SOM metaclasses, and 

SOMCIassMgr the class of the SOMCIassMgrObject, an object created automatically during SOM 

initialization, to maintain a registry of existing classes and to assist in dynamic 
class loading/unloading. 

SOMCIass is defined as a subclass (or child) of SOMObject and inherits all generic object methods; this is why instances of a 
metaclass are class objects (rather than simply classes) in the SOM run time. 

SOM classes are designed to be language neutra/ . That is, SOM classes can be implemented in one programming language and used in 
programs of another language. To achieve language neutrality, the interface for a class of objects must be defined separately from its 
implementation . That is, defining interface and implementation requires two completely separate steps (plus an intervening compile), as 
follows: 



• An interface is the information that a program must know in order to use an object of a particular class. This interface is 
described in an interface definition (which is also the class definition), using a formal language whose syntax is independent of 
the programming language used to implement the class's methods. For SOM classes, this is the SOM Interface Definition 
Language (SOM IDL). The interface is defined in a file known as the /DL source fi/e (or, using its extension, this is often called 
the .ic/i fi/e). 

An interface definition is specified within the interface declaration (or interface statement) of the .idl file, which includes: 

(a) the interface name (or class name) and the name(s) of the class's parent(s), and 

(b) the names of the class's attributes and the signatures of its new methods. (Recall that the complete set 
of available methods also includes all inherited methods.) 

Each method signature includes the method name, and the type and order of its arguments, as well as the type of its return 
value (if any). Attributes are instance variables for which "set" and "get" methods will automatically be defined, for use by the 
application program. (By contrast, instance variables that are not attributes are hidden from the user.) 

• Once the IDL source file is complete, the SOM Compiler is used to analyze the .idl file and create the implementation template 
fi/e , within which the class implementation will be defined. Before issuing the SOM Compiler command, sc, the class 
implementor can set an environment variable that determines which emitters (output-generating programs) the SOM Compiler 
will call and, consequently, which programming language and operating system the resulting binding fi/es will relate to. 
(Alternatively, this emitter information can be placed on the command line for sc.) In addition to the implementation template file 
itself, the binding files include two language-specific header files that will be included in the implementation template file and in 
application program files. The header files define many useful SOM macros, functions, and procedures that can be invoked from 
the files that include the header files. 

• The implementation of a class is done by the class implementor in the imp/ementation temp/ate fi/e (often called just the 
imp/ementation fi/e or the template fi/e). As produced by the SOM Compiler, the template file contains stub procedures for each 
method of the class. These are incomplete method procedures that the class implementor uses as a basis for implementing the 
class by writing the corresponding code in the programming language of choice. 

In summary, the process of imp/ementing a SOM c/ass includes using the SOM IDL syntax to create an IDL source file that specifies the 
interface to a class of objects - that is, the methods and attributes that a program can use to manipulate an object of that class. The SOM 
Compiler is then run to produce an implementation template file and two binding (header) files that are specific to the designated 
programming language and operating system. Finally, the class implementor writes language-specific code in the template file to implement 
the method procedures. 

At this point, the next step is to write the application (or client) program(s) that use the objects and methods of the newly implemented class. 
(Observe, here, that a programmer could write an application program using a class implemented entirely by someone else.) If not done 
previously, the SOM compiler is run to generate usage bindings for the new class, as appropriate for the language used by the client 
program (which may be different from the language in which the class was implemented). After the client program is finished, the 
programmer compiles and links it using a language-specific compiler, and then executes the program. (Notice again, the client program can 
invoke methods on objects of the SOM class without knowing how those methods are implemented.) 



Development of the Tutorial examples 




Example 1-lmplementing a simple class with one method 

Prints a default message when the "sayHello" method is invoked on an object of the "Hello" class. 

Example 2-Adding an attribute to the Hello class 

Defines a "msg" attribute for the "sayHello" method to use. The client program "sets" a message; then the "sayHello" method 
"gets" the message and prints it. (There is no defined message when an object of the "Hello" class is first created.) 

Example 3- Overriding an inherited method 

Overrides the SOMobjects method somPrintSelf so that invoking this method on an object of the "Hello” class will not only 
display the class name and the object's location, but will also include the object's message attribute. 

Example 4-lnitlallzlng a SOM object. 

Overrides the default initialization method, somDefaultlnit, to illustrate how an object's instance variables can be initialized when 
the object is created. 

Example 5-Using multiple inheritance 

Extends the "Hello" class to provide it with multiple inheritance (from the "Disk;" and "Printer" classes.) The "Hello" interface 
defines an enum and an "output" attribute that takes its value from the enum (either "screen,” "printer," or "disk"). The client 
program "sets" the form of "output" before invoking the "sayHello" method to send a "msg"(defined as in Example 4). 



Basic Steps for Implementing SOM Classes 



Implementing and using SOM classes in C or C++ involves the following steps, which are explicitly illustrated in the examples of this tutorial: 

1 . Define the interface to objects of the new class (that is, the interface declaration), by creating a .idl file. 

2. Run the SOM Compiler on the .idl file (by issuing the sc command on AIX or OS/2, or by issuing the some command on 
Windows) to produce the following binding files: 

• Template implementation file 
a .c file for C programmers, or 

a .C file (on AIX) or a .cpp file (on OS/2 or Windows) for C++ programmers; 

• Header file to be included in the implementation file 
a .ih file for C programmers, or 

a .xih file for C++ programmers; and 

• Header file to be included in client programs that use the class 
a .h file for C clients, or 

a .xh file for C++ clients. 

To specify whether the SOM Compiler should produce C or C++ bindings, set the value of the SMEMIT environment variable or 
use the ”-s" option of the sc or some command, as described in Section 4.3, "The SOM Compiler." By default, the SOM 
Compiler produces C bindings. 

3. Customize the implementation, by adding code to the template implementation file. 

4. Create a client program that uses the class. 

5. Compile and link the client code with the class implementation, using a C or C++ compiler. 

6. Execute the client program. 

The following examples illustrate appropriate syntax for defining interface declarations in a .idl file, including designating the methods that 
the class's instances will perform. In addition, example template implementation files contain typical code that the SOM Compiler produces. 
Explanations accompanying each example discuss topics that are significant to the particular example; full explanations of the SOM IDL 
syntax are contained in Chapter 4, "SOM IDL and the SOM Compiler." Customization of each implementation file (step 3) is illustrated in C 
and C++. 




Note: 

1 . The Tutorial assumes you will work through the examples in order. If you do not do so, the code that the SOM Compiler 
generates from your revised .idl file may vary slightly from what you see in the Tutorial. 

2. When the SOMobjects Toolkit is installed, a choice is made between "somcorba" and "somstars" for the style of C bindings the 
SOM Compiler will generate. The Tutorial examples use the "somcorba" style, where an interface name used as a type indicates 
a pointer to an object, as required by strict CORBA bindings. Consequently, as the examples show, a does not explicitly 
appear for types that are pointers to objects. If your system was installed for "somstars" C bindings, you can set the environment 
variable SMADDSTAR=1 or use the SOM Compiler option "-maddstar" to request bindings that use explicit pointer stars. For 
more information, see "Declaring object variables" in Chapter 3, "Using SOM Classes in Client Programs" and "Object types" in 
Chapter 4, "SOM IDL and the SOM Compiler." 



Example 1 -Implementing a Simple Class with One Method 



Example 1 defines a class "FHello" which introduces one new method, "sayHello". When invoked from a client program, the "sayFHello" 
method will print the fixed string "Hello, World!" The example follows the six steps described in the preceding topic, "Basic Steps for 
Implementing SOM Classes." 

1 . Define the interface to class "Hello", which inherits methods from the root class SOMObject and introduces one new method, 
"sayHello". Define these IDL specifications in the file "hello. idl". 

The "interface" statement introduces the name of a new class and any parents (base classes) it may have (here, the root class 
SOMObject). The body of the interface declaration introduces the method "sayHello." Observe that method declarations in IDL 
have syntax similar to C and C++ function prototypes: 

♦include <somobj.idl> //# Get the parent class definition. 

interface Hello : SOMObject 

/* This is a simple class that demonstrates how to define the 
* interface to a new class of objects in SOM IDL. 

*/ 

{ 

void sayHello (); 

// This method outputs the string "Hello, World!". 

/* On Windows, use: string sayHello (); 

* This method returns the string "Hello, World!". */ 

} ; 



Note that the method "sayHello" has no (explicit) arguments and returns no value (except on Windows, which returns a string). 
The characters "II" start a line comment, which finishes at the end of the line. The characters "/*" start a block comment which 
finishes with the Block comments do not nest. The two comment styles can be used interchangeably. Throw-away 
comments are also permitted in a .idl file; they are ignored by the SOM Compiler. Throw-away comments start with the 
characters "//#" and terminate at the end of the line. 

Note: For simplicity, this IDL fragment does not include a releaseorder modifier; consequently, the SOM Compiler will issue a 
warning for the method "sayHello". For directions on using the releaseorder modifier to remove this warning, see the topic 
"Modifier statements" in Chapter 4, "Implementing Classes in SOM." 

2. Run the SOM Compiler to produce binding files and an implementation template (that is, issue the sc command): 

> sc -s"c;h;ih" hello. idl (for C bindings on AIX or OS/2) 

> sc -s"xc; xh; xih" hello. idl (for C++ bindings on AIX or OS/2) 



When set to generate C binding files, the SOM Compiler generates the following implementation template file, named "hello. c". 
The template implementation file contains stub procedures for each new method. These are procedures whose bodies are 
largely vacuous, to be filled in by the implementor. (Unimportant details have been removed for this tutorial.) 

♦include <hello.ih> 

/* 

* This method outputs the string "Hello, World!". 

*/ 



SOM_Scope void SOMLINK sayHello (Hello somSelf, Environment *ev) 




{ 

/* HelloData *somThis = HelloGetData (somSelf ) ; */ 
HelloMethodDebug ( "Hello" , "sayHello") ; 

} 



The terms SOM_Scope and SOMLINK appear in the prototype for all stub procedures, but they are defined by SOM and are not 
of interest to the developer. In the method procedure for the "sayHello" method, "somSelf" is a pointer to the target object (here, 
an instance of the class "Hello") that will respond to the method. A "somSelf" parameter appears in the procedure prototype for 
every method, since SOM requires every method to act on some object. 

The target object is always the first parameter of a method's procedure, although it should not be included in the method's IDL 
specification. The second parameter (which also is not included in the method's IDL specification) is the parameter 
(Environment *ev). This parameter can be used by the method to return exception information if the method encounters an 
error. (Contrast the prototype for the "sayHello" method in steps 1 and 2 above.) 

The remaining lines of the template above are not pertinent at this point. (For those interested, they are discussed in section 5.4 
of Chapter 5, "Implementing SOM Classes.") The file is now ready for customization with the C code needed to implement 
method "sayHello". 

When set to generate C++ binding files, the SOM Compiler generates an implementation template file, "hello. C" (on AIX) or 
"hello. cpp (on OS/2), similar to the one above. (Chapter 5 discusses the implementation template in more detail.) 

Recall that, in addition to generating a template implementation file , the SOM Compiler also generates implementation bindings 
(in a header file to be included in the implementation file) and usage bindings fin a header file to be included in client programs). 
These files are named "hello. ih" and "hello. h" for C bindings, and are "hello. xih" and "hello. xh" for C++ bindings. Notice that the 
"hello. c" file shown above includes the "hello. ih" implementation binding file. 

3. Customize the implementation, by adding code to the template implementation file. 

Modify the body of the "sayHello" method procedure in the "hello. c" (or, for C++, "hello. C" on AIX, "hello. cpp" on OS/2) 
implementation file so that the "sayHello" method prints "Hello, World!": 

SOM_Scope void SOMLINK sayHello (Hello somSelf, Environment *ev) 

{ 

/* HelloData *somThis = HelloGetData (somSelf ) ; */ 

HelloMethodDebug ( "Hello" , "sayHello") ; 

printf ( "Hello, World ! \n" ); 

} 



4. Create a client program that uses the class. 

Write a program "main" that creates an instance (object) of the "Hello" class and invokes the method "sayHello" on that object. 
A C programmer would write the following program in "main.c”, using the bindings defined in the "hello. h" header file: 

/(include <hello.h> 

int main(int argc, char *argv[]) 

{ 

/* Declare a variable to point to an instance of Hello */ 

Hello obj; 

/* Create an instance of the Hello class */ 

obj = HelloNew(); 

/* Execute the "sayHello" method */ 

_sayHello (obj , somGetGlobalEnvironment ( ) ) ; 

/* Free the instance: */ 

_somFree (ob j ) ; 

return (0) ; 

} 



Notice the statement obj = HelloNewO ; The "hello. h" header file automatically contains the SOM-defined macro 
<ctasstVan?e>Uew () , which is used to create an instance of the <c/ass/Vame> class (here, the "Hello" class). 

Also notice that, in C, a method is invoked on an object by using the form: 

_<methodName> (<obj ectName> , <environment_argument> , <o ther_me thod_argumen t s>) 




as used above in the statement _sayHello (ob j , somGetGlobalEnvironment ( ) ) . As shown in this 
example, the SOM-provided somGetGlobalEnvironment function can be used to supply the (Environment *) argument of the 
method. 

Finally, the code uses the method somFree, which SOM also provides, to free the object created by HelloNew ( ) . Notice 
that somFree does not require an (Environment *) argument. This is because the method procedures for some of the classes in 
the SOMobjects Toolkit (including SOMObject, SOMCIass, and SOMCIassMgr) do not have an Environment parameter, to 
ensure compatibility with the previous release of SOM. The documentation for each SOM-kernel method in the SOMobjects 
Deve/oper Too/k/t.- Programmers Reference Manua/ indicates whether an Environment parameter is used. 

A C++ programmer would write the following program in "main.C" (on AIX) or "main.cpp" (on OS/2), using the bindings defined in 
the "hello. xh" header file: 

ftinclude <hello.xh> 

int mainfint argc, char *argv[]) 

{ 

/* Declare a variable to point to an instance of Hello */ 

Hello *obj; 

/* Create an instance of the Hello class */ 

obj = new Hello; 

/* Execute the "sayHello" method */ 

ob j->sayHello (somGetGlobalEnvironment () ) ; 

obj->somFree () ; 

return (0) ; 

} 



Notice that the only argument passed to the "sayFlello” method by a C++ client program is the Environment pointer. (Contrast 
this with the invocation of "sayFlello" in the C client program, above. 

5. Compile and link the client code with the class implementation. 

Note: On AIX or OS/2, the environment variable SOMBASE represents the directory in which SOM has been installed. 

Under AIX, for C programmers: 

> xlc -I. -I$SOMBASE/include -o hello main.c hello. c -L$SOMBASE/lib -1 somtk 

Under AIX, for C++ programmers: 

> xlc -I. -I$SOMBASE/include -o hello main.c hello. C -L$SOMBASE/lib -lsomtk 

Under OS/2, for C programmers: 

> set LIB=%SOMBASE%\lib; %LIB% 

> icc -I. -I%SOMBASE%\include -Fe hello main.c hello. c somtk. lib 

Under OS/2, for C++ programmers: 

> set LIB=%SOMBASE%\lib; %LIB% 

> icc -I. -I\%SOMBASE%\include -Fe hello main.cpp hello. cpp somtk. lib 

6. Execute the client program. 

> hello 
Hello, World! 

Example 2 will extend the "Flello" class to introduce an "attribute.” 



File Extensions for SOM Files 




IDL source file: 


.idl 


for 


all 


users 


Implementation template file: 


. c 


for 


C, < 


all systems 




.C 


for 


C++, 


, on AIX 




.cpp 


for 


C+ + , 


, on OS/2 or Windows 


Header file for implementation 


.ih 


for 


c 




file : 


. xih 


for 


C++ 




Header file for program file: 


.h 


for 


c 






.xh 


for 


C+ + 





Example 2-Adding an Attribute to the Hello class 



Example 1 introduced a class "Hello" which has a method "sayHello" that prints the fixed string "Hello, World!" Example 2 extends the 
"Hello" class so that clients can customize the output from the method "sayHello". 

1 . Modify the interface declaration for the class definition in "hello. idl." 

Class "Hello" is extended by adding an attribute that we call "msg". Declaring an attribute is equivalent to defining "get" and "set" 
methods. For example, specifying: 

attribute string msg; 



is equivalent to defining the two methods: 

string _get_msg(); 

void _set_msg(in string msg); 



Thus, for convenience, an attribute can be used (rather than an instance variable) in order to use the automatically defined "get" 
and "set" methods without having to write their method procedures . The new interface specification for "Hello" that results from 
adding attribute "msg" to the "Hello" class is as follows (with some comment lines omitted): 

♦include <somobj.idl> 

interface Hello : SOMObject 
{ 

void sayHello (); 

attribute string msg; 

//# This is equivalent to defining the methods: 

//# string _get_msg(); 

//# void _set_msg (string msg); 

) ; 



2. Re-run the SOM Compiler on the updated idl file, as in example 1 . This produces new header files and updates the existing 
implementation file, if needed, to reflect changes made to the .idl file. In this example, the implementation file is not modified by 
the SOM Compiler. 

3. Customize the implementation. 

Customize the implementation file by modifying the print statement in the "sayHello" method procedure. This example prints the 
contents of the "msg" attribute (which must be initialized in the client program) by invoking the "_get_msg" method. Notice that, 
because the "_get_msg" method name begins with an underscore, the method is invoked with two leading underscores (for C 
only). 

SOM_Scope void SOMLINK sayHello (Hello somSelf, Environment *ev) 

{ 

/* HelloData *somThis = HelloGetData (somSelf ) ; */ 

HelloMethodDebug ( "Hello" , "sayHello") ; 

print f ("%s\n", get_msg (somSelf , ev) ) ; 




/* for C++, use somSelf->_get_msg (ev) ; */ 



} 



This implementation assumes that "_set_msg" has been invoked to initialize the "msg" attribute before the "_get_msg" method is 
invoked by the "sayHello" method. This initialization can be done within the client program. 

4. Update the client program. 

Modify the client program so that the "_set_msg" method is invoked to initialize the "msg" attribute before the "sayHello" method 
is invoked. Notice that, because the "_set_msg" method name begins with an underscore, the C client program invokes the 
method with two leading underscores. 

For C programmers: 

((include <hello.h> 

int main(int argc, char *argv[] ) 

{ 

Hello obj; 

obj = HelloNewf); 

/* Set the msg text */ 

set_msg(obj, somGetGlobalEnvironment () , "Hello World Again"); 

/* Execute the "sayHello" method */ 

_sayHello (obj, somGetGlobalEnvironment 0 ) ; 

_somFree (ob j ) ; 
return (0) ; 

} 



For C++ programmers: 

((include <hello.xh> 

int main (int argc, char *argv[]) 

{ 

Hello *obj; 
obj = new Hello; 

/* Set the msg text */ 

ob j->_set_msg (somGetGlobalEnvironment () , "Hello World Again"); 

/* Execute the "sayHello" method */ 
ob j->sayHello (somGetGlobalEnvironment () ) ; 

ob j->somFree ( ) ; 
return (0) ; 

} 



5. Compile and link the client program, as before. 

6. Execute the client program: 

> hello 

Hello World Again 



The next example extends the "Hello" class to override (redefine) one of the methods it inherits from its parent class, 

SOMObject. 



Attributes vs instance variables 



As an alternative to defining "numberObjs" as an attribute, it could be defined as an instance variable, with a "get_numberObjs" method also 
defined for retrieving its value. Instance variables are declared in an implementation statement, as shown below: 




interface Hello 
{ 

string get_msg ( ) ; 

void set_msg(in string msg) ; 

#ifdef SOMIDL 

implementation 

{ 

string message ; 

} ; 

#endif 
} ; 



As demonstrated in this example, one disadvantage to using an instance variable is that the "get_msg" and ”set_msg" methods must be 
defined in the implementation file by the class implementor. For attributes, by contrast, default implementations of the "get" and "set" 
methods are generated automatically by the SOM Compiler in the ,ih and ,xih header files. 

Note: For some attributes (particularly those involving structures, strings, and pointers) the default implementation generated by the SOM 
Compiler for the "set” method may not be suitable. This happens because the SOM Compiler only performs a "shallow copy,” which typically 
is not useful for distributed objects with these types of attributes. In such cases, it is possible to write your own implementations, as you do 
for any other method, by specifying the "noset/noget" modifiers for the attribute. (See the subtopic "Modifier statements" in Chapter 4 "SOM 
IDL and the SOM Compiler.") 

Regardless of whether you let the SOM Compiler generate your implementations or not, if access to instance data is required, either from a 
subclass or a client program, then this access should be facilitated by using an attribute. Otherwise, instance data can be defined in the 
"implementation" statement as above (using the same syntax as used to declare variables in C or C++), with appropriate methods defined to 
access it. For more information about "implementation" statements, see the topic "Implementation statements" in Chapter 4. 

As an example where instance variables would be used (rather than attributes), consider a class "Date" that provides a method for returning 
the current date. Suppose the date is represented by three instance variables-”mm", "dd", and "yy”. Rather than making "mm", "dd", and "yy" 
attributes (and allowing clients to access them directly), "Date” defines "mm", "dd", and "yy" as instance variables in the "implementation" 
statement, and defines a method "get_date" that converts "mm", "dd", and "yy” into a string of the form "mm/dd/yy": 

interface Date 
{ 

string getdate ( ) ; 

ftifdef SOMIDL 

implementation 

{ 

long mm,dd,yy; 

} ; 

#endif 
} ; 



To access instance variables that a class introduces from within the class implementation file, two forms of notation are available: 
som This-> var/ab/e/Jame 
or 

_ variab/eName 

For example, the implementation for "get_date" would 



access the "mm" instance variable as somThis->mm or_mm, 
access "dd" as somThis->dd or_dd, and 
access "yy" as somThis->yy or_yy. 

In C++ programs, the _var/ab/eName form is available only if the programmer first defines the macro VARIABLE_MACROS (that is, enter 
#def ine VARIABLE_MACROS) in the implementation file prior to including the ,xih file for the class. 



Example 3-Overriding an Inherited Method 




An important aspect of OOP programming is the ability of a subclass to replace an inherited method implementation with a new 
implementation especially appropriate to its instances. This is called overriding i/o”q. a method. Sometimes, a class may introduce methods 
that every descendant class is expected to override. For example, SOMobject ves introduces the somPrintSelf method, and a good SOM 
programmer will generally override this method when implementing a new class. 

The purpose of somPrintSelf is to print a brief description of an object. The method can be useful when debugging an application that deals 
with a number of objects of the same class -assuming the class designer has overridden somPrintSelf with a message that is useful in 
distinguishing different objects of the class. For example, the implementation of somPrintSelf provided by SOMobjects simply prints the 
class of the object and its address in memory. SOMclass overrides this method so that, when somPrintSelf is invoked on a class object, 
the name of the class will print. 

This example illustrates how somPrintSelf might be overridden for the "Flello" class. An important identifying characteristic of "Flello" objects 
is the message they hold; thus, the following steps illustrate how somPrintSelf could be overridden in "Flello" to provide this information. 

1 . Modify the interface declaration in "hello. idl.” 

To override the somPrintSelf method in "Flello", additionalinformation must be provided in "hello. idl" in the form of an 
implementation statement, which gives extra information about the class, its methods and attributes, and any instance 
variables. (The previous examples omitted the optional "implementation" statement, because it was not needed.) 

In the current example, the "implementation” statement introduces the modifiers for the "Flello" class, as follows. 

♦include <somobj.idl> 

interface Hello : SOMObject 
{ 

void sayHello (); 
attribute string msg; 

ftifdef SOMIDL 

implementation 

{ 

//# Method Modifiers: 

somPrintSelf: override; 

// Override the inherited implementation of somPrintSelf. 

}; 

#endif 

}; 



Flere, "somPrintSelf:" introduces a list of modifiers for the (inherited) somPrintSelf method in the class "Flello". Modifiers are like 
C/C ++ #pragma commands and give specific implementation details to the compiler. This example uses only one modifier, 
"override.” Because of the "override" modifier, when somPrintSelf is invoked on an instance of class "Flello", Hello’s 
implementation of somPrintSelf (in the implementation file) will be called, instead of the implementation inherited from the 
parent class, SOMObject. 

The "#ifdef SOMIDL " and "#endif" are standard C and C++ preprocessor commands that cause the "implementation” 

statement to be read only when using the SOM IDL compiler (and not some other IDL compiler). 

2. Re-run the SOM Compiler on the updated .idl file, as before. The SOM Compiler extends the existing implementation file from 
Example 2 to include new stub procedures as needed (in this case, for somPrintSelf). Below is a shortened version of the C 
language implementation file as updated by the SOM Compiler; C++ implementation files are similarly revised. Notice that the 
code previously added to the "sayFlello" method is not disturbed when the SOM Compiler updates the implementation file. 

♦include <hello.ih> 

SOM_Scope void SOMLINK sayHello (Hello somSelf, Environment *ev) 

{ 

/* HelloData *somThis = HelloGetData (somSelf ) ; */ 

HelloMethodDebug ( "Hello" , "sayHello") ; 

printf ("%s\n", get_msg (somSelf , ev) ) ; 

} 



SOM_Scope void SOMLINK somPrintSelf (Hello somSelf) 

{ 

HelloData *somThis = HelloGetData (somSelf ) ; 
HelloMethodDebug ( "hello" , "somPrintSelf" ) ; 

Hello_parent_SOMOb ject_somPrintSelf (somSelf) ; 




Note that the SOM Compiler added code allowing the "Hello" class to redefine somPrintSelf. The SOM Compiler provides a 
default implementation for overriding the somPrintSelf method. This default implementation simply calls the "parent method" 
[the procedure that the parent class of "Hello" (SOMObject) uses to implement the somPrintSelf method]. This parent method 
call is accomplished by the macro Hello_parent_SOMObject_somPrintSelf defined in "hello. ih." 

Notice that the stub procedure for overriding the somPrintSelf method does not include an Environment parameter. This is 
because somPrintSelf is introduced by SOMObject, which does not include the Environment parameter in any of its methods 
(to ensure backward compatibility). The signature for a method cannot change after it has been introduced. 

3. Customize the implementation. 

Within the new somPrintSelf method procedure, display a brief description of the object, appropriate to "Hello" objects. Note 
that the parent method call is not needed, so it has been deleted. Also, direct access to instance data introduced by the "Hello” 
class is not required, so the assignment to "somThis" has been commented out (see the first line of the procedure). 

SOM_Scope void SOMLINK somPrintSelf (Hello somSelf ) 

{ 

HelloData *somThis = HelloGetData (somSelf ) ; 

HelloMethodDebug ( "Hello" , "somPrintSelf") ; 

somPrintf(" — a %s object at location %x with msg:s\n", 

_somGetClassName (somSelf) , 
somSelf, 

get_msg (somSelf , 0) ) ; 

} 



4. Update the client program to illustrate the change (also notice the new message text): 
For C programmers: 

#include <hello.h> 

int main(int argc, char *argv[] ) 

{ 

Hello obj; 

Environment *ev = somGetGlobalEnvironment ( ) ; 

obj = HelloNewO; 

/* Set the msg text */ 

set_msg (ob j , ev, "Hi There"); 

/* Execute the "somPrintSelf" method */ 

_somPrintSelf (obj) ; 

_somFree (ob j ) ; 
return (0) ; 

} 



For C++ programmers: 

#include <hello.xh> 

int main (int argc, char *argv[]) 

{ 

Hello *obj; 

Environment *ev = somGetGlobalEnvironment () ; 

obj = new Hello; 

/* Set the msg text */ 

setmsg(obj, ev, "Hi There"); 

/* Execute the "somPrintSelf" method */ 

ob j->somPrintSelf () ; 

obj->somFree () ; 
return (0) ; 

} 



5. 



Compile and link the client program, as before. 




6 . 



Execute the client program, which now outputs the message: 



> hello 

— a Hello object at location 20062838 with msg: Hi There 



Example 4 - Initializing a SOM Object 



The previous example showed how to override the method somPrintSelf, introduced by SOMObject. As mentioned in that example, 
somPrintSelf should generally be overridden when implementing a new class. Another method introduced by SOMObject that should 
generally be overridden is somDefaultlnit. The purpose of somDefaultlnit is to provide a "default” initializer for the instance variables 
introduced by a class. 

This example shows how to override somDefaultlnit to give each "Hello" object's message an initial value when the object is first created. 
To learn more about initializers than shown in this example (including how to introduce new initializers that take arbitrary arguments, and 
how to explicitly invoke initializers) read Section 5.5, "Initializing and Uninitializing Objects," in Chapter 5, "Implementing Classes in SOM.” 

The overall process of overriding somDefaultlnit is similar to that of the previous example. First, the IDL for "Hello" is modified. In addition 
to an override modifier, an init modifier is used to indicate that a stub procedure for an initialization method is desired (the stub procedures 
for initializers are different from those of normal methods). 



1 . Modify the interface declaration in "hello. idi.” 



((include <somobj.idl> 

interface Hello : SOMObject 
{ 

void sayHellof); 

attribute string msg; 

ftifdef SOMIDL 

implementation 

{ 

//# Method Modifiers: 
somPrintSelf: override; 

somDefaultlnit: override, init; 

} ; 

#endif 



2. Re-run the SOM Compiler on the updated hello. idi file, as before. SOM Compiler extends the existing implementation file. Beiow 
is the initializer stub procedure that the SOM Compiler adds to the C language implementation file; C++ implementation files 
would be similarly revised: 



SOM_Scope void SOMLINK 

somDefaultlnit (Hello somSelf, somlnitCtrl *ctrl) 

{ 

HelloData *somThis; /* set by Beginlnitializer */ 
somlnitCtrl globalCtrl; 
somBooleanVector myMask; 

HelloMethodDebug ( "Hello" , "somDefaultlnit") ; 
Hello_BeginInitializer_somDef ault Init ; 

Hello_Init_SOMOb ject_somDefaultInit (somSelf , Ctrl) ; 

/* 

* local Hello initialization code added by programmer 
*/ 




3. 



Customize the implementation. 



Here, the "msg" instance variable is set in the implementation template (rather than in the client program, as before). Thus, the 
"msg" is defined as part of the "Hello" object's initialization. 

SOM_Scope void SOMLINK 

somDef aultlnit (Hello somSelf, somlnitCtrl *ctrl) 

{ 

HelloData *somThis; /* set by Beginlnitializer */ 
somlnitCtrl globalCtrl; 
somBooleanVector myMask; 

HelloMethodDebug ( "Hello" , "somDefaultlnit " ) ; 

He llo_Begin Ini tializer_somDef aultlnit ; 

Hello_Init_SOMObject_somDef aultlnit (somSelf , Ctrl) ; 

/* 

* local Hello initialization code added by programmer 
*/ 

set_msg (somSelf , "Initial Message"); 



4. Update the client program to illustrate default initialization. 



#include <hello.h> 
main ( ) 

{ 

Hello h = HelloNewO; 

/* Execute the " somPrintSelf " method */ 

_somPrintSelf (h) ; 

} 



5. Compile and link the client program, as before. 

6. Execute the client program. 



> hello 

— a Hello object at 200633A8 with msg: Initial Message 



Example 5-Using Multiple Inheritance 



The "Hello" class is useful for writing messages to the screen. So that clients can also write messages to printers and disk files, this example 
references two additional classes: "Printer" and "Disk." The "Printer" class will manage messages to a printer, and the "Disk" class will 
manage messages sent to files. These classes can be defined as follows: 

((include <somobj.idl> 

interface Printer : SOMObject 

{ 

void stringToPrinter (in string s) ; 

// This method writes a string to a printer. 

}; 



((include <somobj.idl> 

interface Disk : SOMObject 

{ 

void stringToDisk (in string s) ; 

// This method writes a string to disk. 




This example assumes the "Printer" and "Disk" classes are defined separately (in "print. idl" and "disk.idl," for example), are implemented in 
separate files, and are linked with the other example code. Given the implementations of the "Printer" and "Disk" interfaces, the "Hello" class 
can use them by inheriting from them, as illustrated next. 

1 . Modify the interface declaration in "hello. idl". 

#include <disk.idl> 

#include <printer . idl> 

interface Hello : Disk, Printer 
{ 

void sayHello (); 
attribute string msg; 

enum outputTypes {screen, printer, disk}; 

// Declare an enumeration for the different forms of output 

attribute outputTypes output; 

// The current form of output 

#ifdef SOMIDL 

implementation { 

somDefaultlnit : override, init; 

}; 

#endif //# SOMIDL 

}; 



2 . 



Notice that SOMObject is not listed as a parent of "Hello" above, because SOMObject is a parent of "Disk" (and of "Printer"). 

The IDL specification above declares an enumeration "outputTypes" for the different forms of output, and an attribute "output" 
whose value will depend on where the client wants the output of the "sayHello" method to go. 

Note: SOM IDL allows the use of structures, unions (though with a syntax different from C or C++), enumerations, constants, and 
typedefs, both inside and outside the body of an interface statement. Declarations that appear inside an interface body will be 
emitted in the header file (that is, in "hello. h" or "hello. xh"). Declarations that appear outside of an interface body do not appear in 
the header file (unless required by a special #pragma directive: see the SOM Compiler options in Chapter 4). 

SOM IDL also supports all of the C and C++ preprocessor directives, including conditional compilation, macro processing, and 
file inclusion. 



Re-run the SOM Compiler on the updated idl file.. 

Unfortunately, when this is done, the implementation for somDefaultlnit is not correctly updated to reflect the addition of two 
new parents to "Hello." This is because the implementation file emitter never changes the bodies of existing method procedures. 
As a result, method procedures for initializer methods are not given new parent calls when the parents of a class are changed. 
One way to deal with this (when the parents of a class are changed) is to temporarily rename the method procedure for initializer 
methods, and then run the implementation emitter. Once this is done, the code in the renamed methods can be merged into the 
new templates, which will include all the appropriate parent method calls. When this is done here, the new implementation for 
somDefaultlnit would appear as: 



{ 



SOM_Scope void SOMLINK 

somDefaultlnit (Hello somSelf, somlnitCtrl *ctrl) 

HelloData *somThis; /* set by Beginlnitializer */ 
somlnitCtrl globalCtrl; 
somBooleanVector myMask; 

HelloMethodDebug ( "Hello" , "somDefaultlnit") ; 
Hello_BeginInitializer_somDef aultINit ; 



Hello_Init_Disk_somDef aultlnit (somSelf , Ctrl) ; 
Hello_Init_Printer_somDef aultlnit (somSelf , Ctrl) ; 

/* 

* local Hello initialization code added by programmer 
/* 

set_msg (somSelf , "Initial Message"); 



3. 



Continue to customize the implementation file, hello. c, as follows. Notice that the "sayHello" method (last discussed in Example 




2) is now modified to allow alternate ways of outputing a "msg". 

SOM_Scope void SOMLINK sayHello (Hello somSelf, Environment *ev) 

{ 

/* HelloData *somThis = HelloGetData (somSelf ) ; */ 
HelloMethodDebug ( "Hello" , "sayHello" ) ; 

switch ( ge t_out put (somSelf , ev) ) { 

/* for C++, use: somSelf ->_get_output (ev) */ 

case Hello_screen : 

printf ( "%s\n" , get_msg (somSelf , ev) ); 

/* for C++, use: somSelf->_get_msg (ev) */ 

break; 

case Hello_printer : 

_stringToPrinter (somSelf , ev, get_msg (somSelf , ev) ); 

/* for C++, use: 

* somSelf->stringToPrinter (ev, somSelf->_get_msg (ev) ); 
*/ 

break; 

case Hello_disk: 

_stringToDisk (somSelf , ev, get_msg (somSelf , ev) ); 

/* for C++, use: 

* somSelf->stringToDisk (ev, somSelf->_get_msg (ev) ); 
*/ 

break; 

} 

} 



The "switch" statement invokes the appropriate method depending on the value of the "output" attribute. Notice how the "case" 
statements utilize the enumeration values of "outputTypes" declared in "hello. idl" by prefacing the enumeration names with the 
class name (Hello_screen, Hello_printer, and Hello_disk). 

4. Update the client program, as illustrated next: 

#include <hello.h> 

/* for C++, use "hello. xh" and <stdio.h> */ 

int main(int argc, char *argv[] ) 

{ 

Hello a = HelloNew(); 

Environment *ev = somGetGlobalEnvironment ( ) ; 

/^Invoke "sayHello" on an object and use each output */ 

_sayHello(a, ev) ; /* for C++, use : a->sayHello (ev) ; */ 

set_output (a, ev, Hello_printer) ; 

/* C++ : a->_set_output (ev, Hello_printer) ; */ 

_sayHello(a, ev) ; 

set_output (a, ev, Hello_disk) ; 

/* C++ : a->_set_output (ev, Hello-disk) ; */ 

_sayHello(a, ev) ; 

_somFree (aO ; /* for C++, use: a->somFree ( ) ; */ 

return (0) ; 

} 



5. Compile and link the client program as before, except also include the implementation files for the "Printer" and "Disk" classes in 
the compilation. 

6. Execute the client program. Observe that the message that prints is the "msg" defined in Example 4 as part of the 
somDefaultlnit initialization of the "Hello" object. 

Initial Message 

Initial Message - goes to a Printer 

Initial Message - goes to Disk 



This tutorial has described features of SOM IDL that will be useful to C and C++ programmers. SOM IDL also provides features such as full 
type checking, constructs for declaring private methods, and constructs for defining methods that receive and return pointers to structures. 
Chapter 4, "SOM IDL and the SOM Compiler" gives complete description of the SOM IDL syntax and also describes how to use the SOM 
Compiler. In addition, Chapter 5, "Implementing Classes in SOM," provides helpful information for completing the implementation template, 




for using initializer (somDefaultlnit or user-defined initialization methods), for defining SOM class libraries, and for customizing various 
aspects of SOMobjects execution. 



Using SOM Classes in Client Programs 



This chapter discusses how to use SOM classes that have already been fully implemented. That is, these topics describe the steps that a 
programmer uses to instantiate an object and invoke some method(s) on it from within an application program. 

Who should read this chapter? 

• Programmers who wish to use SOM classes that were originally developed by someone else will need to know the information in 
this chapter. These programmers often may not need the information from any subsequent chapters. 

• By contrast, class implementers who are creating their own SOM classes should continue with Chapter 4, "SOM IDL and the 
SOM Compiler," and Chapter 5, "Implementing Classes in SOM "for complete information on the SOM Interface Definition 
Language (SOM IDL) syntax and other details of class implementation. 

Programs that use a class are referred to as c/ient, programs . A client program can be written in C, in C++, or in another language. As 
noted, this chapter describes how client programs can use SOM classes (classes defined using SOM, as described in Chapter 2, "Tutorial 
for Implementing SOM Classes" and in Chapter 4, "SOM IDL and the SOM Compiler"and Chapter 5 "Implementing Classes in SOM"). Using 
a SOM class involves creating instances of a class, invoking methods on objects, and so forth. All of the methods, functions, and macros 
described here can also be used by class implementers within the implementation file for a class. 

Note: "Using a SOM class," as described in this chapter, does not include subclassing the class in a client program. In particular, the C++ 
compatible SOM classes made available in the .xh binding file can not be subclassed in C++ to create new C++ or SOM classes. 

Some of the macros and functions described here are supplied as part of SOM's C and C++ usage bindings . These bindings are functions 
and macros defined in header files to be included in client programs. The usage bindings make it more convenient for C and C++ 
programmers to create and use instances of SOM classes. SOM classes can be also used without the C or C++ bindings, however. For 
example, users of other programming languages can use SOM classes, and C and C++ programmers can use a SOM class without using 
its language bindings. The language bindings simply offer a more convenient programmer's interface to SOM. Vendors of other languages 
may also offer SOM bindings: check with your language vendor for possible SOM support. 

To use the C or C++ bindings for a class, a client program must include a header file for the class (using the #include preprocessor 
directive). For a C language client program, the file <c/assFi/eStem >. h must be included. For a C++ language client program, the file 
<c/assFi/eStem>x h must be included. The SOM Compiler generates these header files from an IDL interface definition. The header files 
contain definitions of the macros and functions that make up the C or C++ bindings for the class. Whether the header files include bindings 
for the class's private methods and attributes (in addition to the public methods and attributes) depends on the IDL interface definition 
available to the user, and on how the SOM Compiler was invoked when generating bindings. 

Usage binding headers automatically include any other bindings upon which they may rely. Client programs not using the C or C++ bindings 
for any particular class of SOM object (for example, a client program that does not know at compile time what classes it will be using) should 
simply include the SOM-supplied bindings for SOMObject, provided in the header file "somobj.h" (for C programs) or"somobj.xh" (for C++ 
programs). 

For each task that a user of a SOM class might want to perform, this chapter shows how the task would be accomplished by: 

• a C programmer using the C bindings, 

• a C++ programmer using the C++ bindings, or 

• a programmer not using SOM's C or C++ language bindings. 

If neither of the first two approaches is applicable, the third approach can always be used. 



An Example Client Program 



Following is a C program that uses the class "Flello" (as defined in the Tutorial in Chapter 2). The "FHello" class provides one attribute, "msg", 
of type string, and one method, "sayFlello". The "sayFlello" method simply displays the value of the "msg" attribute of the object on which the 
method is invoked. 

ftinclude <hello.h> /* include the header file for Hello */ 



int main(int argc, char *argv[]) 




{ 



/* declare a variable (obj) that is a 

* pointer to an instance of the Hello class: */ 

Hello obj; 

/* create an instance of the Hello class 

* and store a pointer to it in obj: */ 
obj = HelloNewf); 

/* invoke method _set_msg on obj with the argument 

* "Hello World Again". This method sets the value of 

* obj's ' msg' attribute to the specified string. 

*/ 

set_msg(obj, somGetGlobalEnvironment ( ) , "Hello World Again 

/* invoke method sayHello on obj. This method prints 
* the value of obj's 'msg' attribute. */ 

_sayHello (obj, somGetGlobalEnvironment 0 ) ; 

_somFree (ob j ) ; 
return (0) ; 



The C++ version of the foregoing client program is shown below: 

((include <hello.xh> /* include the header file for Hello */ 

int main (int argc, char *argv[]) 

{ 

/* declare a variable (obj) that is a 

* pointer to an instance of the Hello class: */ 

Hello *obj; 

/* create an instance of the Hello class 

* and store a pointer to it in obj: */ 
obj = new Hello; 

/* invoke method _set_msg on obj with the argument 

* "Hello World Again" . This method sets the value of 

* obj's 'msg' attribute to the specified string. */ 

ob j->_set_msg (somGetGlobalEnvironment () , "Hello World Again"); 

/* invoke method sayHello on obj. This method prints 

* the value of obj's 'msg' attribute. */ 
ob j->sayHello (somGetGlobalEnvironment 0 ) ; 

ob j->somFree ( ) ; 
return (0) ; 



These client programs both produce the output: 

Hello World Again 



Using SOM Classes: the Basics 



This section covers the following subjects: 

• Declaring object variables 

• Creating instances of a class 

• Invoking methods on objects 

• Using class objects 

• Compiling and linking 




Declaring object variables 



When declaring an object variable, an object interface name defined in IDL is used as the type of the variable. The exact syntax is slightly 
different for C vs. C++ programmers. Specifically, 

<interface/Vame> obj ; in C programs or 

<interface/Vame> *obj ; in C++ programs 

declares "obj" to be a pointer to an object that has type <interface/Vame>. In SOM, objects of this type are instances of the SOM c/ass 
named </nterfaceName>, or of any SOM class derived from this class. Thus, for example, 

Animal obj; in C programs or 

Animal *obj; in C++ programs 

declares "obj” as pointer to an object of type "Animal" that can be used to reference an instance of the SOM class "Animal" or any SOM 
class derived from "Animal". Note that the type of an object need not be the same as its class/ an object of type "Animal" might not be an 
instance of the "Animal" class (rather, it might be an instance of some subclass of "Animal" - the "Cat" class, perhaps). 

All SOM objects are of type SOMObject, even though they may not be instances of the SOMObject class. Thus, if it is not known at compile 
time what type of object the variable will point to, the following declaration can be used: 

SOMObject obj; in C programs or 

SOMObject *obj; in C++ programs. 

Because the sizes of SOM objects are not known at compile time, instances of SOM classes must always be dynamically allocated. Thus, a 
variable declaration must always define a pointer to an object. 

Note: In the C usage bindings, as within an IDL specification, an interface name used as a type implicitly indicates a pointer to an object that 
has that interface (this is required by the CORBA specification). The C usage bindings for SOM classes therefore hide the pointer with a C 
typedef for <interface/\/ame> . But this is not appropriate in the C++ usage bindings, which define a C++ class for <interface/\/ame> . Thus, it 
is not correct in C++ to use a declaration of the form: 

</nterface/\/ame> obj ; not valid in C++ programs 

Note: If a C programmer also prefers to use explicit pointers to <interface/Vame> types, then the SOM Compiler option -maddstar can be 
used when the C binding files are generated, and the explicit " *" will then be required in declarations of object variables. (This option is 
required for compatibility with existing SOM OIDL code. For information on using the -maddstar option, see "Running the SOM Compiler" in 
Chapter 4, "SOM IDL and the SOM Compiler.") 

Users of other programming languages must also define object variables to be pointers to the data structure used to represent SOM objects. 
The way this is done is programming-language dependent. The header file "somtypes.h" defines the structure of SOM objects for the C 
language. 



Creating instances of a class 



For C programmers with usage bindings. SOM provides the <c/asstVame>He\N and the < c/assName > R e n e w macros for creating 
instances of a class. 

These macros are illustrated with the following two examples, each of which creates a single instance of class "Hello": 

obj = HelloNewf); 

obj = HelloRenew (buffer); 



Using New 



After verifying that the <className> class object exists, the <className>New macro invokes the somNew method on the class object. 




This allocates enough space for a new instance of <className>, creates a new instance of the class, initializes this new object by invoking 
somDefaultlniton it, and then returns a pointer to it. The <className>Newmacro automatically creates the the class object for 
<c/ass/Vame>, as well as its ancestor classes and metaclass, if these objects have not already been created. 

After a client program has finished using an object created using the <c/assName >New macro, the object should be freed by invoking the 
method somFree on it: 

_somFree (ob j ) ; 



After uninitializing the object by invoking somDestruct on it, somFree calls the class object for storage deallocation. This is important 
because storage for an object created using the <c/ass/Vame>Ue\N macro is allocated by the class of the object. Thus, only the class of the 
object can know how to reclaim the object's storage, object for storage deallocation. 



Using Renew 



After verifying that the <className> class object exists, the <className>Renew macro invokes the somRenew method on the class 
object. <className>Renew is only used when the space for the object has been allocated previously. (Perhaps the space holds an old 
uninitialized object that is not needed anymore.) This macro converts the given space into a new, initialized instance of <c/assName> and 
returns a pointer to it. The programmer is responsible for ensuring that the argument of <c/ass/Var> 76 >>Renew points to a block of storage 
large enough to hold an instance of class <c/ass/Vame>. The SOM method somGetlnstanceSize can be invoked on the class to determine 
the amount of memory required. Like <className>New, the <className>Renew macro automatically creates any required class objects 
that have not already been created. 

Hint: When creating a large number of class instances, it may be more efficient to allocate at once enough memory to hold all the instances, 
and then invoke <c/ass/Vame >Renew once for each object to be created, rather than performing separate memory allocations. 



Using NewClass 



The C and C++ usage bindings for a SOM class also provide static linkage to a <className>NewClass function that can be used to create 
the class object. This can be useful if the class object is needed before its instances are created. 

For example, the following C code uses the function HelloNewClass to create the "Hello" class object. The arguments to this function are 
defined by the usage bindings, and indicate the version of the class implementation that is assumed by the bindings. (For more detail on 
creation of classes, see the later section, "Creating a class object.") Once the class object has been created, the example invokes the 
method somGetlnstanceSize on this class to determine the size of a "Hello" object, uses SOMMalloc to allocate storage, and then uses 
the HelloRenew macro to create ten instances of the "Hello" class: 

#include <hello.h> 
main ( ) 

{ 

SOMClass helloCls; /* A pointer for the Hello class object */ 

Hello objA[10]; /* an array of Hello instances */ 

unsigned char ^buffer; 
int i ; 
int size; 

/* create the Hello class object: */ 

helloCls = HelloNewClass (Hello_Ma jorVersion, Hello_MinorVersion) ; 

/* get the amount of space needed for a Hello instance: 

* (somGetlnstanceSize is a method provided by SOM.) */ 
size = _somGetInstanceSize (helloCls) ; 

size = ( (size+3) /4 ) *4 ; /* round up to doubleword multiple */ 

/* allocate the total space needed for ten instances: */ 
buffer = SOMMalloc ( 10*size) ; 

/* convert the space into ten separate Hello instances: */ 
for (i=0; i<10; i++) 

objA[i] = HelloRenew (buf fer+i*size) ; 



/* Uninitialize the objects and free them */ 




for (i=0 ; i<10 ; i++) 

_somDestruct (objA[i] ,0,0) ; 
SOMFree (buffer) ; 

} 



When an object created with the < c/ass Afey77£>>Renew macro is no longer needed, its storage must be freed using the dual to whatever 
method was originally used to allocate the storage. Two method pairs are typical: 

• For example, if an object was originally initialized using the <c/ass/Vame>WwN macro, then, as discussed previously, the client 
should use the somFree method on it. 

• On the other hand, if the program uses the SOMMalloc function to allocate memory, as illustrated in the example above, then 
the SOMFree function must be called to free the objects' storage (because SOMFree is the dual to SOMMalloc). Before this is 
done, the objects in the region to be freed should be deinitialized by invoking the somDestruct method on them. This allows 
each object to free any memory that may have been allocated without the programmer's knowledge. (The somFree method also 
calls the somDestruct method.) 



Note: In the somDestruct method call above, the first zero indicates that memory should not be freed by the class of the object (that is, the 
programmer will do it explicitly). The second zero indicates that the class of the object is responsible for overall control of object 
uninitialization. For further discussion, see Section 5.5, "Initializing and Uninitializing Objects," in Chapter 5, "Implementing Classes in 
SOM." 

For C++ programmers with usage bindings, instances of a class <className> can be created with a new operator provided by the 
usage bindings of each SOM class. The new operator automatically creates the class object for <className>, as well as its ancestor 
classes and metaclass, if they do not yet exist. After verifying the existence of the desired class object, the new operator then invokes the 
somNewNolnit method on the class. This allocates memory and creates a new instance of the class, but it does not initialize the new 
object. Initialization of the new object is then performed using one of the C++ constructors defined by the usage bindings. (For further 
discussion, see Section 5.5 "Initializing and Uninitializing Objects," in Chapter 5, "Implementing Classes in SOM.") Two variations of the new 
operator require no arguments. When either is used, the C++ usage bindings provide a default constructor that invokes the somDefaultlnit 
method on the new object. Thus, a new object initialized by somDefaultlnit would be created using either of the forms: 

new <c/assName> 

new <c/assname>§ 

For example: 



obj = new Hello; 
objl = new Hello (); 



For convenience, pointers to SOM objects created using the newoperator can be freed using the delete operator, just as for normal C++ 
objects (or, the somFree method could be used): 

delete obj; 
objl-> somFree; 



When previously allocated space will be used to hold a new object, C++ programmers should use the somRenew method, described below. 
C++ bindings do not provide a macro for this purpose. 

somNew and somRenew: C and C++ programmers, as well programmers using other languages, can create instances of a class using the 
SOM methods somNew and somRenew, invoked on the class object. As discussed and illustrated above for the C bindings, the class 
object must first be created using the <c/assA/a/ae>NewClass procedure (or, perhaps, using the somFindClass method-see the section 
"Using class objects," to follow later in this chapter). 

The somNew method invoked on the class object creates a new instance of the class, initializes the object using somDefaultlnit, and then 
returns a pointer to the new object. For instance, the following C example creates a new object of the "Flello" class. 

((include <hello.h> 
main ( ) 

{ 

SOMClass helloCls; /* a pointer to the Hello class */ 

Hello obj; /* a pointer to an Hello instance */ 

/* create the Hello class */ 

helloCls = HelloNewClass (Hello_Ma jorVersion, Hello_MinorVersion) ; 
obj = _somNew (helloCls ) ; /* create the Hello instance */ 

} 



An object created using the somNew method should be freed by invoking the somFree method on it after the client program is finished 
using the object. 




The somRenew method invoked on the class object creates a new instance of a class using the given space, rather than allocating new 
space for the object. The method converts the given space into an instance of the class, initializes the new object using somDefaultlnit, and 
then returns a pointer to it. The argument to somRenew must point to a block of storage large enough to hold the new instance. The method 
somGetlnstanceSize can be used to determine the amount of memory required. For example, the following C++ code creates ten 
instances of the "Hello" class: 

ftinclude <hello.xh> 
ftinclude <somcls.xh> 
main ( ) 

{ 

SOMClass *helloCls; // a pointer to the Hello class 
Hello *objA[10] // an array of Hello instance pointers 

unsigned char *buffer; 
int i; 
int size; 

// create the Hello class object 

helloCls = HelloNewClass (Hello_Ma jorVersion, Hello_MinorVersion) ; 

// get the amount of space needed for a Hello instance: 
size = helloCls-> somGetlnstanceSize () ; 

size = ( (size+3 ) /4 ) *4 ; // round up to doubleword multiple 

// allocate the total space needed for ten instances 
buffer = SOMMalloc (10*size) ; 

// convert the space into ten separate Hello objects 
for <1=0; i<10; i++) 

objA[i] = helloCls-> somRenew (buf fer+i*size) ; 

// Uninitialize the objects and free them 
for <1=0; i<10; i++) 

objA[i]-> somDestruct ( 0 , 0 ) ; 

SOMFree (buffer) ; 

} 



The somNew and somRenew methods are useful for creating instances of a class when the header file for the class is not included in the 
client program at compile time. (The name of the class might be specified by user input, for example.) Flowever, the <c/ass/Vame> New 
macro (for C) and the new operator (for C++) can on/y be used for classes whose header file is included in the client program at compile 
time. 

Objects created using the somRenew method should be freed by the client program that allocated it, using the dual to whatever allocation 
approach was initially used. If the somFree method is not appropriate (because the method somNew was not initially used), then, before 
memory is freed, the object should be explicitly deinitialized by invoking the somDestruct method on it. (The somFree method calls the 
somDestruct method. Refer to the previous C example for Renew for an explanation of the arguments to somDestruct.) 



Invoking methods on objects 



This topic describes the general way to invoke methods in C/C+ + and in other languages, and then presents subtopics for more specialized 
situations. 



Making typical method calls 



For C programmers with usage bindings: To invoke a method in C, use the macro: 

_<methoc//\/ame> ( receiver, argsj 

(that is, an underscore followed by the method name). Arguments to the macro are the receiver of the method followed by all of the 
arguments to the method. For example: 



foo(obj, somGetGlobalEnvironment ( ) , x, y) 




This invokes method "too" on ”obj" (the remaining arguments are arguments to the method "too"). This expression can be used anywhere 
that a standard function call can be used in C. 

Required arguments 

In C. calls to methods defined using IDL require at least two arguments - a pointer to the receiving object (the object responding to the 
method) and a value of type (Environment *). The Environment data structure is specified by CORBA, and is used to pass environmental 
information between a caller and a called method. For example, it is used to return exceptions. (For more information on how to supply and 
use the Environment structure, see the later section entitled "Exceptions and error handling.'') 

In the IDL definition of a method, by contrast, the receiver and the Environment pointer are not listed as parameters to the method. (Unlike 
the receiver, the Environment pointer is considered a method parameter, even though it is never explicitly specified in IDL. For this reason, 
it is called an imp/icit method parameter.) For example, if a method is defined in a .idl file with two parameters, as in: 

int foo (in char c, in float f) ; 



then, with the C usage bindings, the method would be invoked with four arguments, as in: 

intvar = __foo(obj, somGetGlobalEnvironment ( ) , x, y) ; 



where "obj" is the object responding to the method and "x" and "y" are the arguments corresponding to "c" and "f", above. 

If the IDL specification of the method includes a context specification, then the method has an additional (implicit) context parameter. Thus, 
when invoking the method, this argument must follow immediately after the Environment pointer argument. (None of the SOM-supplied 
methods require context arguments.) The Environment and context method parameters are prescribed by the CORBA standard. 

If the IDL specification of the class that introduces the method includes the callstyle=oidl modifier, then the (Environment*) and context 
arguments should not be supplied when invoking the method. That is, the receiver of the method call is followed immediately by the 
arguments to the method (if any). Some of the classes supplied in the SOMobjects Toolkit (including SOMObject, SOMCIass, and 
SOMCIassMgr) are defined in this way, to ensure compatibility with the previous release of SOM. The System Object Mode/ Programming 
Reference specifies for each method whether these arguments are used. 

If you use a C expression to compute the first argument to a method call (the receiver), you must use an expression without side effects, 
because the first argument is evaluated twice bv the _<metiioc//\/ame> macro expansion. In particular, a somNew method call or a macro 
call of <c/ass/iame> New can not be used as the first argument to a C method call, because doing so would create two new class instances 
rather than one. 

Following the initial, required arguments to a method (the receiving object, the Environment, if any, and the context, if any), you enter any 
additional arguments required by that method, as specified in IDL. For a discussion of how IDL in/out/inout argument types may to C/C++ 
data types, see the topic "Parameter list" in Chapter 4, "SOM IDL and the SOM Compiler.” 

Short form vs long form 

If a client program uses the bindings for two different classes that introduce or inherit two different methods of the same name , then the 
_<method/\/ame> macro described above (called the short form) will not be provided by the bindings, because the macro would be 
ambiguous in that circumstance. The following iong form macro, however, is always provided by the usage bindings for each class that 
supports the method: 

<c/assName>_<methodName> ( receiver, args) 

For example, method "foo" supported by class "Bar" can be invoked as: 

Bar_foo(obj, somGetGlobalEnvironment () , x, y) (in C) 

where "obj" has type "Bar" and "x" and "y" are the arguments to method "foo". 

In most cases (where there is no ambiguity, and where the method is not a vajist method, as described in the subsequent subtopic "Using 
'vajist' methods”), a C programmer may use either the short or the long form of a method invocation macro interchangeably. Flowever, on/v 
the Iona form complies with the CORBA standard for C usage bindings . If you wish to write code that can be easily ported to other vendor 
platforms that support the CORBA standard, use the long form exclusively. The long form is always available for every method that a class 
supports. The short form is provided both as a programming convenience and for source code compatibility with release 1 of SOM. 

In order to use the long form, a programmer will usually know what type an object is expected to have. If this is not known, but the different 
methods have the same signature, the method can be invoked using name-lookup resolution, as described in a following subtopic of this 
section. 

For C++ programmers with usage bindings : To invoke a method, use the standard C++ form shown below: 



o'd\-xmethod/\/ame> [args) 




where args are the arguments to the method. For instance, the following example invokes method "foo" on "obj": 



ob j->foo (somGetGlobalEnvironment ( ) , x, y) 

Required arguments 

All methods introduced by classes declared using IDL (except those having the SOM IDL callstyle=oidl modifier) have at least one 
parameter -a value of type (Environment *). The Environment data structure is used to pass environmental information between a caller 
and a called method. For example, it is used to return exceptions. For more information on how to supply and use the Environment 
structure, see the later section entitled "Exceptions and error handling." 

The Environment pointer is an implicit parameter; in the IDL definition of a method, the Environment pointer is not explicitly listed as a 
parameter to the method. For example, if a method is defined in IDL with two explicit parameters, as in: 

int foo (in char c, in float f ) ; 



then the method would be invoked from C++ bindings with three arguments, as in: 

intvar = obj->foo (somGetGlobalEnvironment () , x, y) ; 



where "obj" is the object responding to the method and "x" and "y" are the arguments corresponding to "c" and "f", above. 

If the IDL specification of the method includes a context specification, then the method has a second implicit parameter, of type context, 
and the method must be invoked with an additional context argument. This argument must follow immediately after the Environment 
pointer argument . (No SOM-supplied methods require context arguments.) The Environment and context method parameters are 
prescribed by the CORBA standard. 

If the IDL specification of the class that introduces the method includes the callstyle=oidl modifier, then the (Environment *) and context 
arguments should not be supplied when the method is invoked. Some of the classes supplied in the SOMobjects Toolkit (including 
SOMObject, SOMCIass, and SOMCIassMgr) are defined in this way, to ensure compatibility with the previous release of SOM. The 
System Object Mode/ Programming Reference specifies for each method whether these arguments are used. 

Following the initial, required arguments to a method (the receiving object, the Environment, if any, and the context, if any), you enter any 
additional arguments required by that method, as specified in IDL. For a discussion of how IDL in/out/inout argument types map to C/C++ 
data types, see the topic "Parameter list" in Chapter 4, "SOM IDL and the SOM Compiler." 

For non-C/C++ programmers : To invoke a static method (that is, a method declared when defining an OIDL or IDL object interface) 
without using the C or C++ usage bindings, a programmer can use the somResolve procedure. The somResolve procedure takes as 
arguments a pointer to the object on which the method is to be invoked and a method token for the desired method. It returns a pointer to 
the method's procedure (or raises a fatal error if the object does not support the method). Depending on the language and system, it may be 
necessary to cast this procedure pointer to the appropriate type: the way this is done is language-specific. 

The method is then invoked by calling the procedure returned by somResolve (the means for calling a procedure, given a pointer to it, is 
language-specific), passing the method's receiver, the Environment pointer (if necessary), the context argument (if necessary) and the 
remainder of the method's arguments, if any. (See the section above for C programmers; the arguments to a method procedure are the 
same as the arguments passed using the long form of the C-language method-invocation macro for that method.) 

Using somResolve requires the programmer to know where to find the method token for the desired method. Method tokens are available 
from class objects that support the method (via the method somGetMethodToken), or from a global data structure, called the C/assData 
structure, corresponding to the class that introduces the method. In C and C++ programs with access to the definitions for ClassData 
structures provided by usage bindings, the method token for method methodName introduced by class c/assName may be accessed by 
the following expression: 

<c/assName> ClassData. <method/\/ame > 

For example, the method token for method "sayFlello"introduced by class "Flello" is stored at location 

HelloClassData . sayHello, for C and C++ programmers. The way method tokens are accessed in other languages is 
language-specific. 

As an example of using offset resolution to invoke methods from a programming language other than C/C++, one would do the following to 
create an instance of a SOM Class X\n Smalltalk: 

1 . Initialize the SOM run-time environment, if it has not previously been initialized, using the somEnvironmentNew function. 

2. If the class object for class X has not yet been created, use somResolve with arguments SOMCIassMgrObject (returned by 
somEnvironmentNew in step 1) and the method token for the somFindClass method, to obtain a method procedure pointer 
for the somFindClass method. Use the method procedure for somFindClass to create the class object for class X: Call the 
procedure with arguments SOMCIassMgrObject, the result of calling the somldFromString function with argument "X", and 
the major and minor version numbers for class X (or zero). The procedure returns the class object for class X . 




3. Use somResolve with arguments representing the class object for X (returned by somFindClass in step 2) and the method 
token for the somNew method, to obtain a method procedure pointer for method somNew. (The somNew method is used to 
create instances of class X.) 

4. Call the method procedure for somNew (using the method procedure pointer obtained in step 3) with the class object for X 
(returned by somFindClass in step 3) as the argument. The procedure returns a new instance of class X. 

In addition to somResolve, SOM also supplies the somClassResolve procedure. Instead of an object, the somClassResolve procedure 
takes a class as its first argument, and then selects a method procedure from the instance method table of the passed class. (The 
somResolve procedure, by contrast, selects a method procedure from the instance method table of the class of which the passed object is 
an instance.) The somClassResolve procedure therefore supports casted method resolution. See the System Object Mode/ Programming 
Reference for more information on somResolve and somClassResolve. 

If the programmer does not know at compile time which class introduces the method to be invoked, or if the programmer cannot directly 
access method tokens, then the procedure somResolveByName can be used to obtain a method procedure using name-lookup resolution, 
as described in the next section. 

If the signature of the method to be invoked is not known at compile time, but can be discovered at run time, use somResolve or 
somResolveByName to get a pointer to the somDispatch method procedure, then use it to invoke the specific method, as described below 
under "Method name or signature not known at compile time." 



Accessing Attributes 



In addition to methods, SOM objects can also have attributes. An attribute is an IDL shorthand for declaring methods, and does not 
necessarily indicate the presence of any particular instance data in an object of that type. Attribute methods are called "get” and "set" 
methods. For example, if a class "Flello" declares an attribute called "msg", then object variables of type "Flello" will support the methods 
_get_msg and _set_msg to access or set the value of the "msg" attribute. (Attributes that are declared as "readonly" have no "set" method, 
however.) 

The "get" and "set" methods are invoked in the same way as other methods. For example, given class "Flello" with attribute "msg" of type 
string, the following code segments set and get the value of the "msg" attribute: 

ForC: 



#include <hello.h> 

Hello obj; 

Environment *ev = somGetGlobalEnvironment () ; 
obj = HelloNewO; 

set_msg(obj, ev, "Good Morning" ); /*note : two leading underscores */ 

printf ( "%s\n" , get_msg(obj, ev) ) ; 



For C++: 

#include <hello.xh> 

♦include <stdio.h> 

Hello *obj; 

Environment *ev = somGetGlobalEnvironment () ; 
obj = new Hello; 

ob j->_set_msg (ev, "Good Morning"); 
printf ( "%s\n" , ob j->_get jnsg (ev) ) ; 



Attributes available with each class, if any, are described in the documentation of the class itself in the System Object Mode/ Programming 
Reference. 



Using 'vajist' methods 



SOM supports methods whose final argument is a vajist. A vajist is a data type whose representation depends on the operating-system 
platform. To aid construction of portable code, SOM supports a platform-neutral API for building and manipulating vajists. Use of this API 
is recommended on all platforms because it is compliant with the ANSI C standard and because of its portability. 




Note: Initially support for vajist functions is available only for the PowerPC platform. With the release of SOM 3.0 however, support is 
extended to the PC platform. 



A function to create a vajist is not provided. Instead, users declare local variables of type somVaBuf and vajist. 
The following sequence of calls is used to create and destroy a vajist: 

• somVaBuf_create 

Creates a SOM buffer for variable arguments from which the vajist will be built. 

• somVaBuf_add 

Adds an argument to the SOM buffer for variable arguments. 

• somVaBuf_get_valist 

Copies the vajist from the SOM buffer. 

• somVaBuf_destroy 

Releases the SOM buffer and its associated vajist. 

• somvalistSetTarget 

Modifies the first scalar value on the vajist without other side effects. 

• somvalistGetTarget 

Gets the first scalar value from the vajist without other side effects. 



Detailed information on these functions is provided in the System Object Mode/ Programming Reference . 

Examples of vajist usage 

The following code segments pass a vajist to the somDispatch method by using the SOMobjects functions that build the vajist. 

The somDispatch method (introduced by SOMObject) is a particularly useful method whose final argument is a vajist. As explained in the 
System Object Mode/ Programming Reference , somDispatch can be used to invoke some other method (called the "dispatched" method) 
on an object when usage bindings for the dispatched method are not available or when the method to be dispatched is not known until run 
time. The vajist argument for somDispatch holds the arguments that will be passed to the dispatched method, including the target object 
for the dispatched method. 

ForC: 



((include <somobj.h> 

void fl (SOMObject obj. Environment *ev) 
{ 

char *msg; 
va_list start_val; 
somVaBuf vb; 

char *msgl = "Good Morning"; 



vb = (somVaBuf ) somVaBuf_creata (NULL, 0) ; 



(char 


*)&obj, tk_pointer) ; 












/* 


target for _set 


_msg */ 


(char 


*) &ev, tk_pointer) ; 












/* 


next argument 


*/ 


(char 


*) &msgl, tk_pointer) ; 












/* 


final argument 


*/ 


st (vb, 


&start_val) ; 









/* dispatch _set_msg on object */ 

SOMObject somDispatch ( 

obj, /* target for somDispatch */ 

0, /* says ignore dispatched method result */ 

somldFromString ( "_set_msg" ) , /* the somld for _set_msg */ 

start_val) ; /* target and args for _set_msg */ 

/* dispatch _get_msg on obj: */ 

/* Get a fresh copy of the va_list */ 

somVaBuf_get_valist (vb, &start_val) ; 




SOMOb ject_somDi spat ch ( 

ob j , 

(somToken *)&msg, 

/* address to store dispatched result */ 
somldFromString ( "_get_msg" ) , 

start_val) ; /* target and arguments for _get_msg */ 

printf ("%s\n",msg) ; 

somVaBuf_destroy (vb) ; 



For C++: 



#include <somobj.h> 

void fl (SOMObject obj, Environment *ev) 

{ 

char *msg; 
va_list start_val; 
somVaBuf vb; 

char *msgl = "Good Morning"; 



vb = (somVaBuf ) somVaBuf_create (NULL, 0); 
somVaBuf_add (vb, (char *)&obj, tk_pointer) ; 

/* target for _set_msg */ 
somVaBuf_add (vb, (char *)&ev, tk_pointer) ; 

/* next argument */ 

somVaBuf_add (vb, (char *)&msgl, tk_pointer) ; 

/* final argument */ 

somVaBuf_get_valist (vb, &start_val) ; 



/* dispatch _set_msg on object */ 
ob j-> SOMOb ject_somDi spat ch ( 

0, /* says ignore dispatched method result */ 

somldFromString ( "_set_msg" ) , /* the somld for _set_msg */ 

start_val) ; /* target and args for _set_msg */ 



/* dispatch _get_msg on obj: */ 

/* Get a fresh copy of the va_list */ 

somVaBuf_get_valist (vb, &start_val) ; 
ob j-> SOMOb ject_somDi spat ch ( 

(somToken *)&msg, 

/* address to store dispatched result */ 
somldFromString ( "_get_msg" ) , 

start_val) ; /* target and arguments for _get_msg */ 

printf (”%s\n",msg) ; 

somVaBuf_destroy ( vb) ; 



As a convenience, methods whose final argument is a vajist can be invoked from C and C++ by using the short form of method invocation 
and specifying a variable number of arguments in place of the vajist. That is, beginning at the syntax position where the vajist argument 
is expected, SOMobjects interprets all subsequent arguments as being the components of the vajist. This is illustrated below, using the 

somDispatch method. 

As an example of using the variable-argument interface to somDispatch, the following code segments illustrate how an example of attribute 
access (in the topic "Accessing attributes") could be recoded to operate without usage bindings for the "Hello" class. These code segments 
are expressed as functions that accept an argument of type SOMObject under the assumption that bindings for "Hello" are not available. 
(This requires usage bindings for SOMObject, which are also required for calling somDispatch.) 

ForC: 

#include <somobj.h> 

void fl (SOMObject obj. Environment *ev) 

{ 

char *msg; 

/* dispatch _set_msg on obj: */ 

_somDispatch ( 

obj, /* the target for somDispatch */ 

0, /* says ignore the dispatched method result */ 

somldFromString ( "_set_msg" ) , /* the somld for _set_msg */ 

obj, /* the target for _set_msg */ 

ev, /* the other arguments for _set_msg */ 

"Good Morning"); 

/* dispatch _get_msg on obj: */ 

_somDispatch ( 

ob j , 

(somToken *)&msg. 




/* address to hold dispatched method result */ 
somldFromString ( "_get_msg" ) , 
obj, /* the target for _get_msg */ 
ev) ; /* the other argument for _get_msg */ 

printf ( " %s\n" , msg) ; 

} 



For C++: 

#include <somobj.h> 

void fl (SOMObject obj. Environment *ev) 

{ 

char *msg; 

/* dispatch _set_msg on obj: */ 

ob j->somDispatch ( 

0, /* says ignore the dispatched method result */ 

somldFromString ( "_set_msg" ) , /* dispatched method id */ 

obj, /* the target for _set_msg */ 

ev, /* the other arguments for _set_msg */ 

"Good Morning"); 

/* dispatch _get_msg on obj: */ 

ob j->somDispatch ( 

(somToken *)&msg, 

/* address to store dispatched result */ 
somldFromString ( "_get_msg" ) , 
ob j , 
ev) ; 

printf ( "%s\n" , msg); 

} 



C programmers must be aware that the "short form" of the invocation macro that is used above to pass a variable number of arguments to a 
vajist method is only available in the absence of ambiguity. The long-form macro (which is always available) requires an explicit vajist 
argument. (See "Short form vs long form" under "Making typical method calls" earlier in this chapter.) 



Using name-lookup method resolution 



For C/C++ programmers : Offset resolution is the most efficient way to select the method procedure appropriate to a given method call. 
Client programs can, however, invoke a method using "name-lookup" resolution instead of offset resolution. The C and C++ bindings for 
method invocation use offset resolution by default, but methods defined with the namelookup SOM IDL modifier result in C bindings in 
which the short form invocation macro uses name-lookup resolution instead. Also, for both C and C++ bindings, a special 
iookup_<method/\iame> macro is defined. 

Name-lookup resolution is appropriate in the case where a programmer knows at compile time which arguments will be expected by a 
method (that is, its signature ), but does not know the type of the object on which the method will be invoked. For example, name-lookup 
resolution can be used when two different classes introduce different methods of the same name and signature , and it is not known which 
method should be invoked (because the type of the object is not known at compile time). 

Name-lookup resolution is also used to invoke dynamic methods (that is, methods that have been added to a class's interface at run time 
rather than being specified in the class's IDL specification). For more information on name-lookup method resolution, see the topic "Method 
Resolution" in Chapter 4, "SOM IDL and the SOM Compiler." 

For C : To invoke a method using name-lookup resolution, when using the C bindings for a method that has been implemented with the 
namelookup modifier , use either of the following macros: 



_<method/\/ame> ( receiver, args ) 

\ooV,\i'p_<methodiVame> {rece/Ver, args ) 

Thus, the short-form method invocation macro results in name-lookup resolution (rather than offset resolution), when the method has been 
defined as a namelookup method. (The long form of the macro for offset resolution is still available in the C usage bindings.) If the method 
takes a variable number of arguments, then the first form shown above is used when supplying a variable number of arguments, and the 
second form is used when supplying a vajist argument in place of the variable number of arguments. 



For C++ : To invoke a method using name-lookup resolution, when using the C++ bindings for a method that has been defined with the 
namelookup modifier , use either of the following macros: 




\ooVM'p_<met/JocfA/ame> [receiver. argsj 



<c/assName> _\ooV.u'p_<meff)ocfiVame> {receiver, argsj 

If the method takes a variable number of arguments, then the first form shown above is used when supplying a variable number of 
arguments, and the second form is used when supplying a vajist argument in place of the variable number of arguments. Note that the 
offset-resolution forms for invoking methods using the C++ bindings are also still available, even if the method has been defined as a 

namelookup method. 

For C/C++ To invoke a method using name-lookup resolution, when the method has not been defined as a namelookup method : 

• Use the somResolveByName procedure (described in the following section), or any of the methods somLookupMethod, 
somFindMethod or somFindMethodOk to obtain a pointer to the procedure that implements the desired method. 

• Then, invoke the desired method bv calling that procedure , passing the method's intended receiver, the Environment pointer (if 
needed), the context argument (if needed), and the remainder of the method's arguments, if any. 

The somLookupMethod, somFindMethod and somFindMethodOK methods are invoked on a class object (the class of the method 
receiver should be used), and take as an argument the somld for the desired method (which can be obtained from the method's name using 
the somldFromString function). For more information on these methods, see the System Object Mode/ Programming Reference . 

Important Note: SOM provides many ways for a SOM user to acquire a pointer to a method procedure. Once this is done, it becomes the 
user's responsibility to make appropriate use of this procedure. 

• First, the procedure should only be used on objects for which this is appropriate-otherwise, run-time errors are likely to result. 

• Second, when the procedure is used, it is essential that the compiler be given correct information concerning the signature of the 
method and the linkage required by the method. (On many systems, there are different ways to pass method arguments, and 
linkage information tells a compiler how to pass the arguments indicated by a method's signature). 

SOM method procedures on OS/2 must be called with "system" linkage. On AIX, there is only one linkage convention for procedure calls. 
While C and C++ provide standard ways to indicate a method signature, the way to indicate linkage information depends on the specific 
compiler and system. For each method declared using OIDL or IDL, the C and C++ usage bindings therefore use conditional macros and a 
typedef to name a type that has the correct linkage convention. This type name can then be used by programmers with access to the usage 
bindings for the class that introduces the method whose procedure pointer is used. The type is named 

somTD_ <c/ass/\tame> _<mettiod/\/ame> . This is illustrated in the following example, and further details are provided in the section below, 
titled "Obtaining a method's procedure pointer." 



A name-lookup example 



The following example shows the use of name-lookup by a SOM client programmer. Name-lookup resolution is appropriate when a 
programmer knows that an object will respond to a method of some given name, but does not know enough about the type of the object to 
use offset method resolution. Flow can this happen? It normally happens when a programmer wants to write generic code, using methods of 
the same name and signature that are applicable to different classes of objects, and yet these classes have no common ancestor that 
introduces the method. This can easily occur in single-inheritance systems (such as Smalltalk and SOM release 1) and can also happen in 
multiple-inheritance systems such as SOM release 2-when class hierarchies designed by different people are brought together for clients' 
use. 

If multiple inheritance is available, it is always possible to create a common class ancestor into which methods of this kind can be migrated. 
A refactoring of this kind often implements a semantically pleasing generalization that unifies common features of two previously unrelated 
class hierarchies. This step is most practical, however, when it does not require the redefinition or recompilation of current applications that 
use offset resolution. SOM is unique in that it allows this. 

Flowever, such refactoring must redefine the classes that originally introduced the common methods (so the methods can be inherited from 
the new "unifying” class instead). A client programmer who simply wants to create an application may not control the implementations of the 
classes. Thus, the use of name-lookup method resolution seems the best alternative for programmers who do not want to define new 
classes, but simply to make use of available ones. 

For example, assume the existence of two different SOM classes, "classX" and "classY", whose only common ancestor is SOMObject, and 
who both introduce a method named "reduce" that accepts a string as an argument and returns a tong. We assume that the classes were 
not designed in conjunction with each other. As a result, it is unlikely that the "reduce" method was defined with a namelookup modifier. 
The following figure illustrates the class hierarchy for this example. 





Following is a C++ generic procedure that uses name-lookup method resolution to invoke the "reduce" method on its argument, which may 
be either of type "classX" or "classY". Note that there is no reason to include classY's usage bindings, since the typedef provided for the 
"reduce" method procedure in "classX" is sufficient for invoking the method procedure, independently of whether the target object is of type 
"classX" or "classY". 

((include <classX.xh> // use classX 's method proc typedef 

// this procedure can be invoked on a target of type 
// classX or classY. 

long generic_reducel (SOMObject *target, string arg) 

{ 

somTD_classX_reduce reduceProc = (somTD_classX_reduce) 

somResolveByName (target , "reduce") ; 

return reduceProc (target , arg); 

} 



On the other hand, If the classes were designed in conjunction with each other, and the class designer felt that programmers might want to 
write generic code appropriate to either class of object, the namelookup modifier might have been used. This is a possibility in SOM release 
2, even with multiple inheritance, but it is much more likely that the class designer would use multiple inheritance to introduce the reduce 
method in a separate class, and then use this other class as a parent for both classX and classY (thereby allowing the use of offset 
resolution). 

In any case, if the "reduce" method in "classX" were defined as a namelookup method, the following code would be appropriate. Note that 
the name-lookup support provided by "classX" usage bindings is still appropriate for use on targets that do not have type "classX". As a 
result, the "reduce" method introduced by "classY" need not have been defined as a namelookup method. 

((include <classX.xh> // use classX 's name-lookup support 

// this procedure can be invoked on a target of type 
// classX or classY. 

long generic_reduce2 (SOMObject *target, string arg) 

{ 

return lookupreduce (target, arg); 

} 



For non-C/C++ programmers: Name-lookup resolution is useful for non-C/C++ programmers when the type of an object on which a 
method must be invoked is not known at compile time or when method tokens cannot be directly accessed by the programmer. To invoke a 




method using name-lookup resolution when not using the C or C++ usage bindings, use the somResolveByName procedure to acquire a 
procedure pointer. How the programmer indicates the method arguments and the linkage convention in this case is compiler specific. 

The somResolveByName procedure takes as arguments a pointer to the object on which the method is to be invoked and the name of the 
method, as a string. It returns a pointer to the method's procedure (or NULL if the method is not supported by the object). The method can 
then be invoked by calling the method procedure, passing the method's receiver, the Environment pointer (if necessary), the context 
argument (if necessary), and the rest of the method's arguments, if any. (See the section above for C programmers; the arguments to a 
method procedure are the same as the arguments passed to the long-form C-language method-invocation macro for that method.) 

As an example of invoking methods using name-lookup resolution using the procedure somResolveByName, the following steps are used 
to create an instance of a SOM Class X\ n Smalltalk: 

1 . Initialize the SOM run-time environment (if it is not already initialized) using the somEnvironmentNew function. 

2. If the class object for class X has not yet been created, use somResolveByName with the arguments SOMCIassMgrObject 
(returned by somEnvironmentNew in step 1) and the string "somFindC/ass", to obtain a method procedure pointer for the 
somFindClass method. Use the method procedure for somFindClass to create the class object for class X: Call the method 
procedure with these four arguments: SOMCIassMgrObject; the variable holding class X's somld (the result of calling the 
somldFromString function with argument "X")] and the major and minor version numbers for class X (or zero). The result is the 
class object for class X. 

3. Use somResolveByName with arguments the class object for X (returned by somFindClass in step 2) and the string 
"somNew\ to obtain a method procedure pointer for method somNew. (This somNew method is used to create instances of a 
class.) 

4. Call the method procedure for somNew (using the method procedure pointer obtained in step 3) with the class object for X 
(returned by somFindClass in step 3) as the argument. The result is a new instance of class X. How the programmer indicates 
the method arguments and the linkage convention is compiler-specific. 



Obtaining a method's procedure pointer 



Method reso/ution is the process of obtaining a pointer to the procedure that implements a particular method for a particular object at run 
time. The method is then invoked subsequently by calling that procedure, passing the method's intended receiver, the Environment pointer 
(if needed), the context argument (if needed), and the method's other arguments, if any. C and C++ programmers may wish to obtain a 
pointer to a method's procedure for efficient repeated invocations. 

Obtaining a pointer to a method's procedure is achieved in one of two ways, depending on whether the method is to be resolved using 
offset resolution or name-lookup resolution. Obtaining a method's procedure pointer via offset resolution is faster, but it requires that the 
name of the class that introduces the method and the name of the method be known at compile time . It also requires that the method be 
defined as part of that class's interface in the IDL specification of the class. (See the topic "Method Resolution" in Chapter 4, "SOM IDL and 
the SOM Compiler" for more information on offset and name-lookup method resolution.) 



Offset resolution 



To obtain a pointer to a procedure using offset resolution, the C/C++ usage bindings provide the SOM_Resolve and 
SOM_ResolveNoCheck macros. The usage bindings themselves use the first of these, SOM_Resolve, for offset-resolution method calls. 
The difference in the two macros is that the SOM_Resolve macro performs consistency checking on its arguments, but the macro 
SOM_ResolveNoCheck, which is faster, does not. Both macros require the same arguments: 

SOM_Resolve(</e , C6 , /i/<?/>, <c/assName > , <methodName>) SOM_ResolveNoCheck(</s’C'6 , /i/ l ?A>, <c/ass/tame > , < methodName > ) 
where the arguments are as follows: 

receiver The object to which the method will apply. It should be specified as an expression without side 

effects. 

c/assName The name of the class that introduces the method. 

methodName The name of the desired method. 

These two names ( c/assName and method/Vame ) must be given as tokens, rather than strings or expressions. (For example, as Animal 




rather than "Animal".) If the symbol SOM_TestOn is defined and the symbol SOM_NoTest is not defined in the current compilation unit, 
then SOM_Resolve verifies that rece/Ver is an instance of c/assName or some class derived from c/assName . If this test fails, an error 
message is output and execution is terminated. 

The SOM_Resolve and SOM_ResolveNoCheck macros use the procedure somResolve to obtain the entry-point address of the desired 
method procedure (or raise a fatal error if method/Vame is not introduced by c/assName). This result can be directly applied to the method 
arguments, or stored in a variable of generic procedure type (for example, somMethodPtr) and retained for later method use. This second 
possibility would result in a loss of information, however, for the reasons now given. 

The SOM_Resolve or SOM_ResolveNoCheck macros are especially useful because they cast the method procedure they obtain to the 
right type to allow the C or C++ compiler to call this procedure with system linkage and with the appropriate arguments. This is why the 
result of SOM_Resolve is immediately useful for calling the method procedure, and why storing the result of SOM_Resolve in a variable of 
some "generic" procedure type results in a loss of information. The correct type information can be regained, however, because the type 
used by SOM_Resolve for casting the result of somResolve is available from C/C++ usage bindings using the typedef name 
somTD_ <c/assName>_<methodName>. This type name describes a pointer to a method procedure for method/Vame introduced by class 
c/assName. If the final argument of the method is a vajist, then the method procedure returned by SOM_Resolve or 
SOM_ResolveNoCheck must be called with a vajist argument, and not a variable number of arguments. 

Below is a C example of using SOM_Resolve to obtain a method procedure pointer for method "sayHello", introduced by class "Hello", and 
using it to invoke the method on "obj." (Assume that the only argument required by the "sayHello" method is the Environment pointer.) 

somMethodProc *p; 

SOMObject obj = HelloNewO; 
p = SOM_Resolve (ob j , Hello, sayHello); 

( (somTD_Hello_say Hello) p) (obj, somGetGlobalEnvironment () ) ; 



SOM_Resolve and SOM_ResolveNoCheck can only be used to obtain method procedures for static methods (methods that have been 
declared in an IDL specification for a class) and not methods that are added to a class at run time. See the System Object Mode/ 
Programming Reference for more information and examples on SOM_Resolve and SOM_ResolveNoCheck. 



Name-lookup method resolution 



To obtain a pointer to a method's procedure using name-lookup resolution, use the somResolveByName procedure (described in the 
following section), or any of the somLookupMethod, somFindMethod and somFindMethodOK methods. These methods are invoked on 
a class object that supports the desired method, and they take an argument specifying the a somld for the desired method (which can be 
obtained from the method's name using the somldFromString function). For more information on these methods and for examples of their 
use, see the System Object Mode/ Programming Reference . 



Method name or signature not known at compile time 



If the programmer does not know a method's name at compile time (for example, it might be specified by user input), then the method can 
be invoked in one of two ways, depending upon whether its signature is known: 

• Suppose the signature of the method is known at compile time (even though the method name is not). In that case, when the 
name of the method becomes available at run time, the somLookupMethod, somFindMethod or somFindMethodOk methods 
or the somResolveByName procedure can be used to obtain a pointer to the method's procedure using name-lookup method 
resolution, as described in the preceding topics. That method procedure can then be invoked, passing the method's intended 
receiver, the Environment pointer (if needed), the context argument (if needed), and the remainder of the method's arguments. 

• If the method's signature is unknown until run time, then dispatch-function resolution is indicated, as described in the next topic. 



Dispatch-function method resolution 



If the signature of the method is not known at compile time (and hence the method's argument list cannot be constructed until run time) 
then the method can be invoked at run time by (a) placing the arguments in a variable of type vajist at run time and (b) either using the 




somGetMethodData method followed by use of the somApply function, or by invoking the somDispatch or somClassDispatch method. 
Using somApply is more efficient, since this is what the somDispatch method does, but it requires two steps instead of one. In either case, 
the result invokes a "stub" procedure called an app/ystub , whose purpose is to remove the method arguments from the vajist, and then 
pass them to the appropriate method procedure in the way expected by that procedure. For more information on these methods and for 
examples of their use, see the somApply function, and the somGetMethodData, somDispatch, and somClassDispatch methods in the 
System Object Mode/ Programm/ng Reference . 



Using class objects 



Using a class object encompasses three aspects: getting the class of an object, creating a new class object, or simply referring to a class 
object through the use of a pointer. 



Getting the class of an object 



To get the class that an object is an instance of, SOM provides a method called somGetClass. The somGetClass method takes an object 
as its only argument and returns a pointer to the class object of which it is an instance. For example, the following statements store in 
"myClass" the class object of which "obj” is an instance. 

myClass = _somGetClass (ob j ) ; (for C) 
myClass = ob j->somGetClass ( ) ; (for C++) 

Getting the class of an object is useful for obtaining information about the object; in some cases, such information cannot be obtained 
directly from the object, but only from its class. The section below entitled "Getting information about a class" describes the methods that 
can be invoked on a class object after it is obtained using somGetClass. 

The somGetClass method can be overridden by a class to provide enhanced or alternative semantics for its objects. Because it is usually 
important to respect the intended semantics of a class of objects, the somGetClass method should normally be used to access the class of 
an object. 

In a few special cases, it is not possible to make a method call on an object in order to determine its class. For such situations, SOM 
provides the SOM_GetClass macro. In general, the somGetClass method and the SOM_GetClass macro may have different behavior (if 
somGetClass has been overridden). This difference may be limited to side effects, but it is possible for their results to differ as well. The 
SOM_GetClass macro should only be used when absolutely necessary. 



Creating a class object 



A class object is created automatically the first time the <c/ass/\/ame> New macro (for C) or the new operator (C++) is invoked to create an 
instance of that class. In other situations, however, it may be necessary to create a class object explicitly , as this section describes. 



Using Renew or somRenew 



It is sometimes necessary to create a class object before creating any instances of the class. For example, creating instances using the 
<c/assName> Renew macro or the somRenew method requires knowing how large the created instance will be, so that memory can be 
allocated for it. Getting this information requires creating the class object (see the example under "Creating instances of a class" early in this 
chapter). As another example, a class object must be explicitly created when a program does not use the SOM bindings for a class. Without 
SOM bindings for a class, its instances must be created using somNew or somRenew, and these methods require that the class object be 
created in advance. 

Use the <c/ass/Vame> NewClass procedure to create a class object: 



When using the C/C++ language bindings for the class, and 




When the name of the class is known at compile time. 



Using NewClass 



The <c/assA/a/??e>Ne\NC\ass procedure initializes the SOM run-time environment, if necessary, creates the class object (unless it already 
exists), creates class objects for the ancestor classes and metaclass of the class, if necessary, and returns a pointer to the newly created 
class object. After its creation, the class object can be referenced in client code using the macro 

_<c/assName> (for C and C++ programs) 

or the expression 

<c/ass/Vame> ClassData.classObject (for C and C++ programs). 

The <c/assName> NewClass procedure takes two arguments, the major version number and minor version number of the class. These 
numbers are checked against the version numbers built into the class library to determine if the class is compatible with the client's 
expectations. The class is compatible if it has the same major version number and the same or a higher minor version number . If the class is 
not compatible, an error is raised. Major version numbers usually only change when a significant enhancement or incompatible change is 
made to a class. Minor version numbers change when minor enhancements or fixes are made. Downward compatibility is usually 
maintained across changes in the minor version number. Zero can be used in place of version numbers to bypass version number checking. 

When using SOM bindings for a class, these bindings define constants representing the major and minor version numbers of the class at the 
time the bindings were generated. These constants are named <c/assName>_ MajorVersion and <c/assA/ame>_N\mot\lets\on. For 
example, the following procedure call: 

AnimalNewClass (Animal_Ma jorVersion, Animal_MinorVersion) ; 



creates the class object for class "Animal”. Thereafter, _Animal can be used to reference the "Animal” class object. 

The preceding technique for checking version numbers is not failsafe. For performance reasons, the version numbers for a class are only 
checked when the class object is created, and not when the class object or its instances are used. Thus, run-time errors may result when 
usage bindings for a particular version of a class are used to invoke methods on objects created by an earlier version of the class. 



Using somFindClass or somFindCIsInFile 



To create a class object when not using the C/C++ language bindings for the class, or when the class name is not known at compile time : 

• First, initialize the SOM run-time environment by calling the somEnvironmentNew function (unless it is known that the SOM 
run-time environment has already been initialized). 

• Then, use the somFindClass or somFindCIsInFile method to create the class object. (The class must already be defined in a 
dynamically linked library, or DLL.) 

The somEnvironmentNew function initializes the SOM run-time environment. That is, it creates the four primitive SOM objects (SOMCIass, 
SOMObject, SOMCIassMgr, and the SOMCIassMgrObject), and it initializes SOM global variables. The function takes no arguments and 
returns a pointer to the SOMCIassMgrObject. 



Note: Although somEnvironmentNew must be called before using other SOM functions and methods, explicitly calling 

somEnvironmentNew is usually not necessary when using the C/C++ bindings, because the macros for <c/assA/a/77e>NewC\ass , 
<c/assA/a/ae >New , and < c/ass A/ame>Renew call it automatically, as does the new operator for C++. Calling somEnvironmentNew 
repeatedly does no harm. 



After the SOM run-time environment has been initialized, the methods somFindClass and somFindCIsInFile can be used to create a class 
object. These methods must be invoked on the class manager , which is pointed to by the global variable SOMCIassMgrObject. (It is also 
returned as the result of somEnvironmentNew.) 



The somFindClass method takes the following arguments: 




c/ass/d 



A somld identifying the name of the class to be created. The somldFromString 
function returns a c/ass/d given the name of the class. 



major version number The expected major version number of the class. 

minor version number The expected minor version number of the class. 

The version numbers are checked against the version numbers built into the class library to determine if the class is compatible with the 
client's expectations. 

The somFindClass method dynamically loads the DLL containing the class's implementation, if needed, creates the class object (unless it 
already exists) by invoking its <c/ass/Vame> NewClass procedure, and returns a pointer to it. If the class could not be created, 
somFindClass returns NULL. For example, the following C code fragment creates the class "Flello" and stores a pointer to it in "myClass": 

SOMClassMgr cm = somEnvironmentNew ( ) ; 
somld classld = somldFromString ( "Hello" ) ; 

SOMClass myClass = _somFindClass (SOMClassMgrObject, classld 

Hello_Ma jorVersion, Hello_MinorVersion) ; 

SOMFree (classld) ; 



The somFindClass method uses somLocateClassFile to get the name of the library file containing the class. If the class was defined with 
a "dllname" class modifier, then somLocateClassFile returns that file name; otherwise, it assumes that the class name is the name of the 
library file. The somFindCIsInFile method is similar to somFindClass, except that it takes an additional (final) argument-the name of the 
library file containing the class. The somFindCIsInFile method is useful when a class is packaged in a DLL along with other classes and the 
"dllname” class modifier has not been given in the class's IDL specification. 

Warning: On AIX, the somFindClass and somFindCIsInFile methods should not be used to create a class whose implementation is 
statically linked with the client program. Instead, the class object should be created using the <c/assName >NewClass procedure provided 
by the class's .h/.xh header file. Static linkage is not created by including usage bindings in a program, but by use of the offset-resolution 
method-invocation macros. 

Invoking methods without corresponding class usage bindings 

This topic builds on the preceding discussion, and illustrates how a client program can apply dynamic SOM mechanisms to utilize classes 
and objects for which specific usage bindings are not available. This process can be applied when a class implementor did not ship the 
C/C++ language bindings. Furthermore, the process allows more programming flexibility, because it is not necessary to know the class and 
method names at compile time in order to access them at run time. (At run time, however, you must be able to provide the method 
arguments, either explicitly or via a vajist, and provide a generalized way to handle return values.) As an example application, a 
programmer might create an online class viewer that can access many classes without requiring usage bindings for all those classes, and 
the person using the viewer can select class names at run time. 

As another aspect of flexibility, a code sequence similar to the following C++ example could be re-used to access any class or method. After 
getting the somld for a class name, the example uses the somFindClass method to create the class object. The somNew method is then 
invoked to create an instance of the specified class, and the somDispatch method is used to invoke a method on the object. 

((include <stdio.h> 

((include <somcls.xh> 

int main ( ) 

{ 

SOMClass *classobj; 
somld templd; 
somld methld; 

SOMObject *s2 ; 

Environment * main_ev = somGetGlobalEnvironment ( ) ; 

templd = SOM_IdFromString ( "myClassName" ) ; 

classobj = SOMClassMgrOb ject->somFindClass (templd, 0 , 0 ) ; 

SOMFree (templd) ; 

if (NULL==classob j ) 

{ 

printf ( "somFindClass could not find the selected class\n") ; 



else 

{ 

s2 = (SOMObject *) (classob j->somNew ( ) ) ; 

methld = somldFromString (" sayHello" ) ; 

if (s2->somDispatch ( (somToken *) 0, methld, s2, ev) ) 

printf ( "Method successfully called. \n"); 




return 0; 



Referring to class objects 



Saving a pointer as the class object is created : The <o/assAtan?e>tie\NCiass macro and the somFindClass method, used to create 
class objects, both return a pointer to the newly created class object. Hence, one way to obtain a pointer to a class object is to save the 
value returned by <c/ass/Vame> NewClass or somFindClass when the class object is created. 

Getting a pointer after the class object is created : After a class object has been created, client programs can also get a pointer to the 
class object from the class name. When the class name is known at compile time and the client program is using the C or C++ language 
bindings, the macro 

_< c/ass A/ame> 

can be used to refer to the class object for <c/ass/Vame>. Also, when the class name is known at compile time and the client program is 
using the C or C++ language bindings, the expression 

<ctassA/anje >C\assData.c\assOb\ect 

refers to the class object for <c/ass/Vame>. For example, _Hello refers to the class object for class "Hello" in C or C++ programs, and 
HelloClassData . classOb ject refers to the class object for class "Hello." in C or C++ programs. 

Getting a pointer to the class object from an instance : If any instances of the class are known to exist, a pointer to the class object can 
also be obtained by invoking the somGetClass method on such an instance. (See "Getting the class of an object," above.) 

Getting a pointer in other situations : If the class name is not known until run time, or if the client program is not using the C or C++ 
language bindings, and no instances of the class are known to exist, then the somClassFromld method can be used to obtain a pointer to 
a class object after the class object has been created. The somClassFromld method should be invoked on the class manager, which is 
pointed to by the global variable SOMCIassMgrObject. The only argument to the method is a somld for the class name, which can be 
obtained using the somldFromString function. The method somClassFromld returns a pointer to the class object of the specified class. 
For example, the following C code stores in "myClass" a pointer to the class object for class "Hello" (or NULL, if the class cannot be 
located): 

SOMClassMgr cm = somEnvironmentNew ( ) ; 
somld classld = somldFromString ( "Hello" ) ; 

SOMClass myClass =_somClassFromId (SOMCIassMgrObject, classld 

Hello_Ma jorVersion, Hello_MinorVersion) ; 

SOMFree (classld) ; 



Compiling and linking 



This section describes how to compile and link C and C++ client programs. Compiling and linking a client program with a SOM class is done 
in one of two ways, depending on how the class is packaged. 

Note: If you are building an application that uses a combination of C and C++ compiled object modules, then the C++ linker must be used to 
link them. 

If the class is not packaged as a library (that is, the client program has the implementation source code for the class, as in the examples 
given in the SOM IDL tutorial), then the client program can be compiled together with the class implementation file as follows. (This assumes 
that the client program and the class are both implemented in the same language, C or C++. If this is not the case, then each module must 
be compiled separately to produce an object file and the resulting object files linked together to form an executable.) 

In the following examples, the environment variable SOMBASE refers to the directory in which SOM has been installed. The examples also 
assume that the header files and the import library for the "Hello" class reside in the "include" and "lib" directories where SOM has been 
installed. If this is not the case, additional path information should be supplied for these files. For client program "main" and class "Hello": 




Under AIX, for C programmers: 



> xlc -I. -I$SOMBASE/include main.c hello. c -L$SOMBASE/lib -lsomtk \ 
-o main 



Under AIX, for C++ programmers: 

> xlc -I. -I$SOMBASE/ include main.C hello. C -L$SOMBASE/lib -lsomtk \ 
-o main 



Under OS/2, for C programmers: 

> set LIB=%SOMBASE%\lib; %LIB% 

> icc -I. -I%SOMBASE%\include main.c hello. c somtk.lib 

Under OS/2, for C++ programmers: 

> set LIB=%SOMBASE%\lib; %LIB% 

> icc -I. -I%SOMBASE%\include main.cpp hello. cpp somtk.lib 



If the class is packaged as a class library , then the client program, "main", is compiled as above, except that the class implementation file 
is not part of the compilation. Instead, the "import library" provided with the class library is used to resolve the symbolic references that 
appear in "main". For example, to compile the C client program "main.c" that uses class "Flello": 

Under AIX: 

> xlc -I. -I$SOMBASE/include main.c -lc -L$SOMBASE/lib -lsomtk \ 

-lhello -o main 



Under OS/2: 

> set LIB=%SOMBASE%\lib; %LIB% 

> icc -I. -I%SOMBASE%\include main.c somtk.lib hello. lib 



Language-neutral Methods and Functions 



This section describes methods, functions, and macros that client programs can use regardless of the programming language in which they 
are written. In other words, these functions and methods are not part of the C or C++ bindings. 



Generating output 



The following functions and methods are used to generate output, including descriptions of SOM objects. They all produce their output using 
the character-output procedure held by the global variable SOMOutCharRoutine. The default procedure for character output simply writes 
the character to stdout, but it can be replaced to change the output destination of the methods and functions below. (See Chapter 5 for 
more information on customizing SOM.) 

somDumpSelf (method) writes a detailed description of an object, including its class, its location, 

and its instance data. The receiver of the method is the object to be dumped. An 
additional argument is the "nesting level" for the description. [All lines in the 
description will be indented by (2 * level) spaces.] 

somPrintSelf (method) Writes a brief description of an object, including its class and location in 

memory. The receiver of the method is the object to be printed. 



somPrintf 



(function) SOM's version of the C "printf" function. It generates character stream 
output via SOMOutCharRoutine. It has the same interface as the C "printf" 




function. 



somVprintf (function) Represents the "vprint" form of somPrintf. Its arguments are a 

formatting string and a vajist holding the remaining arguments. 

somPrefixLevel (function) Generates (via somPrintf) spaces to prefix a line at the indicated level. 

The return type is void. The argument is an integer specifying the level. The 
number of spaces generated is (2 * level). 

somLPrintf (function) Combines somPrefixLevel and somPrintf. The first argument is the 

level of the description (as for somPrefixLevel) and the remaining arguments are 
as for somPrintf (or for the C "printf" function). 

See the System Object Mode/ Programm/ng Reference for more information on a specific function or method. 



Getting information about a class 



The following methods are used to obtain information about a class or to locate a particular class object: 



somCheckVersion 



somClassFromld 



somDescendedFrom 



somFindClass 



somFindCIsInFile 



Checks a class for compatibility with the specified major and minor version 
numbers. The receiver of the method is the SOM class about which information is 
needed. Additional arguments are values of the major and minor version numbers. 
The method returns TRUE if the class is compatible, or FALSE otherwise. 

Finds the class object of an existing class when given its somld, but without 
loading the class. The receiver of the method is the class manager (pointed to by 
the global variable SOMCIassMgrObject). The additional argument is the class's 
somld. The method returns a pointer to the class (or NULL if the class does not 
exist). 

Tests whether one class is derived from another. The receiver of the method is the 
class to be tested, and the potential ancestor class is the argument. The method 
returns TRUE if the relationships exists, or FALSE otherwise. 

Finds or creates the class object for a class, given the class's somld and its major 
and minor version numbers. The receiver of the method is the class manager 
(pointed to by the global variable SOMCIassMgrObject). Additional arguments 
are the class's somld and the major and minor version numbers. The method 
returns a pointer to the class object, or NULL if the class could not be created. 

Finds or creates the class object for a class. This method is similar to 
somFindClass, except the user also provides the name of a file to be used for 
dynamic loading, if needed. The receiver of the method is the class manager 
(pointed to by the global variable SOMCIassMgrObject). Additional arguments 
are the class's somld, the major and minor version numbers, and the file name. 
The method returns a pointer to the class object, or NULL if the class could not be 
created. 



somGetlnstancePartSize 



somGetlnstanceSize 



somGetName 



Obtains the size of the instance variables introduced by a class. The receiver of 
the method is the class object. The method returns the amount of space, in bytes, 
needed for the instance variables. 

Obtains the total size requirements for an instance of a class. The receiver of the 
method is the class object. The method returns the amount of space, in bytes, 
required for the instance variables introduced by the class itself and by all of its 
ancestor classes. 

Obtains the name of a class. The receiver of the method is the class object. The 
method returns the class name. 



somGetNumMethods Obtains the number of methods available for a class. The receiver of the method is 

the class object. The method returns the total number of currently available 
methods (static or otherwise, including inherited methods). 



somGetNumStaticMethods 



Obtains the number of static methods available for a class. (A static method is one 
declared in the class's interface specification [.idl] file.) The receiver of the method 
is the class object. The method returns the total number of available static 




methods, including inherited ones. 



somGetParents Obtains a sequence of the parent (base) classes of a specified class. The receiver 

of the method is the class object. The method returns a pointer to a linked list of 
the parent (base) classes (unless the receiver is SOMObject, for which it returns 
NULL). 

somGetVersionNumbers Obtains the major and minor version numbers of a class. The return type is void, 

and the two arguments are pointers to locations in memory where the method can 
store the major and minor version numbers (of type long). 

somSupportsMethod Indicates whether instances of a given class support a given method. The receiver 

of the somSupportsMethod method is the class object. The argument is the 
somld for the method in question. The somSupportsMethod method returns 
TRUE if the method is supported, or FALSE otherwise. 

See the System Object Mode/ Programm/ng Reference for more information on a specific method. 



Getting information about an object 



The following methods and functions are used to obtain information about an object (instance) or to determine whether a variable holds a 
valid SOM object. 



Methods 



somGetClass 



somGetClassName 



somGetSize 



somlsA 



somlsInstanceOf 



somRespondsTo 



Gets the class object of a specified object. The receiver of the method is the object 
whose class is desired. The method returns a pointer to the object's corresponding 
class object. 

Obtains the class name of an object. The receiver of the method is the object 
whose class name is desired. The method returns a pointer to the name of the 
class of which the specified object is an instance. 

Obtains the size of an object. The receiver of the method is the object. The 
method returns the amount of contiguous space, in bytes, that is needed to hold 
the object itself (not including any additional space that the object may be using or 
managing outside of this area). 

Determines whether an object is an instance of a given class or of one of its 
descendant classes. The receiver of the method is the object to be tested. An 
additional argument is the name of the class to which the object will be compared. 
This method returns TRUE if the object is an instance of the specified class or if 
(unlike somlsInstanceOf) it is an instance of any descendant class of the given 
class; otherwise, the method returns FALSE. 

Determines whether an object is an instance of a specific class (but not of any 
descendant class). The receiver of the method is the object. The argument is the 
name of the class to which the object will be compared. The method returns TRUE 
if the object is an instance of the specified class, or FALSE otherwise. 

Determines whether an object supports a given method. The receiver of the 
method is the object. The argument is the somld for the method in question. (A 
somld can be obtained from a string by using the somldFromString function.) 

The somRespondsTo method returns TRUE if the object supports the method, or 
FALSE otherwise. 



Functions 




somlsObj Takes as its only argument an address (which may not be valid). The function 

returns TRUE (1) if the address contains a valid SOM object, or FALSE (0) 
otherwise. This function is designed to be failsafe. 

See the System Object Mode/ Programm/ng Reference for more information on a specific method or function. 



Debugging 



The following macros are used to conditionally generate output for debugging. All output generated by these macros is written using the 
replaceable character-output procedure pointed to by the global variable SOMOutCharFtoutine. The default procedure simply writes the 
character to stdout , but it can be replaced to change the output destination of the methods and functions below. (See Chapter 5 for more 
information on customizing SOM.) 

Debugging output is produced or suppressed based on the settings of three global variables, SOM_TraceLevel, SOM_WarnLevel, and 
SOMAssertLevel : 

• SOMTraceLevel controls the behavior of the <c/ass/Vame>Me thodDebug macro; 

• SOMWarnLevel controls the behavior of the macros SOMWarnMsg, SOMTestC, and SOMExpect; and 

• SOMAssertLevel controls the behavior of the SOM_Assert macro. 

Available macros for generating debugging output are as follows: 

<c/assA/ame>Metho<iDebug (macro for C and C++ programmers using the SOM language bindings for 

<c/assName> ) 

The arguments to this macro are a class name and a method name. If the 
SOM_TraceLevel global variable has a nonzero value, the 
<className>MethodDebug macro produces a message each time the specified 
method (as defined by the specified class) is executed. This macro is typically 
used within the procedure that implements the specified method. (The SOM 
Compiler automatically generates calls to the <c/ass/Vame>MethodDebug macro 
within the implementation template files it produces.) u To suppress method 
tracing for all methods of a class, put the following statement in the implementation 
file after including the header file for the class: 

#define <classi\Tame>MethodDebug (c, m) \ 

SOM_NoTrace (c, m) 



SOMTestC 



SOMWarnMsg 



SOMAssert 



SOMExpect 



This can yield a slight performance improvement. The SOMMTraced metaclass, 
discussed below, provides a more extensive tracing facility that includes method 
parameters and returned values. 

The SOM_TestC macro takes as an argument a boolean expression. If the 
boolean expression is TRUE (nonzero) and SOM_AssertLevel is greater than 
zero, then an informational message is output. If the expression is FALSE (zero) 
and SOM_WarnLevel is greater than zero, a warning message is produced. 

The SOM_WarnMsg macro takes as an argument a character string. If the value 
of SOM_WarnLevel is greater than zero, the specified message is output. 

The SOM_Assert macro takes as arguments a boolean expression and an error 
code (an integer). If the boolean expression is TRUE (nonzero) and 
SOM_AssertLevel is greater than zero, then an informational message is output. 
If the expression is FALSE (zero), and the error code indicates a warning-level 
error and SOM_WarnLevel is greater than zero, then a warning message is 
output. If the expression is FALSE and the error code indicates a fatal error, then 
an error message is produced and the process is terminated. 

The SOM_Expect macro takes as an argument a boolean expression. If the 
boolean expression is FALSE (zero) and SOM_WarnLevel is set to be greater 
than zero, then a warning message is output. If cond/t/on is TRUE and 
SOM_AssertLevel is set to be greater than zero, then an informational message 




is output. 



See the System Object Moc/e/ Programming Reference for more information on a specific macro. 

The somDumpSelf and somPrintSelf methods can be useful in testing and debugging. The somPrintSelf method produces a brief 
description of an object, and the somDumpSelf method produces a more detailed description. See the System Object Mode/ Programming 
Reference for more information. 



Checking the validity of method calls 



The C and C++ language bindings include code to check the validity of method calls at run time. If a validity check fails, the SOM_Error 
macro ends the process. (SOM_Error is described below.) To enable method-call validity checking, place the following directive in the client 
program prior to any #/nc/ude directives for SOM header files: 

#define SOM_TestOn 



Alternatively, the -DSOM_TestOn option can be used when compiling the client program to enable method-call validity checking. 



Exceptions and error handling 



In the classes provided in the SOM run-time library (that is, SOMCIass, SOMObject, and SOMCIassMgr), error handling is performed by a 
user-replaceable procedure, pointed to by the global variable SOMError, that produces an error message and an error code and, if 
appropriate ate, ends the process where the error occurred. (Chapter 5 describes how to customize the error handling procedure.) 

Each error is assigned a unique integer error code. Errors are grouped into three categories, based on the last digit of the error code: 

SOMJgnore This category of error represents an informational event. The event is considered 

normal and can be ignored or logged at the user's discretion. Error codes having a 
last digit of 2 belong to this category. 

SOM_Warn This category of error represents an unusual condition that is not a normal event, 

but is not severe enough to require program termination. Error codes having a last 
digit of 1 belong to this category. 

SOM_Fatal This category of error represents a condition that should not occur or that would 

result in loss of system integrity if processing were allowed to continue. In the 
default error handling procedure, these errors cause the termination of the process 
in which they occur. Error codes having a last digit of 9 belong to this category. 

The various codes for all errors detected by SOM are listed in Appendix A, "Customer Support and Error Codes." 

When errors are encountered in client programs or user defined-classes, the following two macros can be used to invoke the error-handling 
procedure: 

SOM_Error The SOM_Error macro takes an error code as its only argument and invokes the 

SOM error handling procedure (pointed to by the global variable SOMError) to 
handle the error. The default error handling procedure prints a message that 
includes the error code, the name of the source file, and the line number where the 
macro was invoked. If the last digit of the error code indicates a serious error (of 
category SOM_Fatal), the process causing the error is terminated. (Chapter 5 
describes how to customize the error handling procedure.) 

SOM_Test The SOM_Test macro takes a boolean expression as an argument. If the 

expression is TRUE (nonzero) and the SOM_AssertLevel is greater than zero, 
then an informational message is output. If the expression is FALSE (zero), an 
error message is produced and the program is terminated. 

See the System Object Mode/ Programm/ng Reference for more information on a specific macro. 

Other classes provided by the SOMobjects Toolkit (including those in the Persistence, Replication, DSOM, and Interface Repository 
frameworks, and the utility classes and metaclasses) handle errors differently. Rather than invoking SOMError with an error code, their 




methods return exceptions via the (Environment *) inout parameter required by these methods. The following sections describe the 
exception declarations, the standard exceptions, and how to set and get exception information in an Environment structure. 



Exception declarations 



As discussed in Chapter 4 in the section entitled "SOM Interface Definition Language,” a method may be declared to return zero or more 
exceptions. IDL exceptions are implemented by simply passing back error information after a method call, as opposed to the "catch/throw" 
model where an exception is implemented by a long jump or signal. Associated with each type of exception is a name, and optionally, a 
struct-like data structure for holding error information. A method declares the types of exceptions it may return in a raises expression. 

Below is an example IDL declaration of a "BAD_FLAG" exception, which may be "raised" by a"checkFlag" method, as part of a "MyObject" 
interface: 

interface MyObject { 

exception BAD_FLAG { long ErrCode; char Reason[80];} 
void checkFlag (in unsigned long flag) raises (BAD_FLAG) ; 

}; 



An exception structure contains whatever information is necessary to help the caller understand the nature of the error. The exception 
declaration can be treated like a struct definition: i.e., whatever you can access in an IDL struct, you can access in an exception 
declaration. Alternatively, the structure can be empty , whereby the exception is just identified by its name. 

The SOM Compiler will map the exception declaration in the above example to the following C language constructs: 

typedef struct BAD_FLAG { 
long ErrCode; 
char Reason [80]; 

} BAD_FLAG; 

#def ine ex_BAD_FLAG "MyObject :: BAD_FLAG" 



When an exception is detected, the "checkFlag" method must call SOMMalloc to allocate a "BAD_FLAG" structure, initialize it with the 
appropriate error information, and make a call to somSetException (see "Setting an exception value," below) to record the exception value 
in the Environment structure passed in the method call. The caller, after invoking "checkFlag", can check the Environment structure that 
was passed to the method to see if there was an exception, and if so, extract the exception value from the Environment (see "Getting an 
exception value," below.) 



Standard exceptions 



In addition to user-defined exceptions (those defined explicitly in an IDL file), there are several predefined exceptions for system run-time 
errors. A system exception can be returned on any method call. (That is, they are implicitly declared for every method whose class uses IDL 
call style, and they do not appear in any raises expressions.) The standard exceptions are listed in Table 2 of Section 4.2, "SOM Interface 
Definition Language". Most of the predefined system exceptions pertain to Object Request Broker errors. Consequently, these types of 
exceptions are most likely to occur in DSOM applications (Chapter 6). 

Each of the standard exceptions has the same structure: an error code (to designate the subcategory of the exception) and a completion 
status code. For example, the NO_MEMORY standard exception has the following definition: 

enum completion_status {YES, NO, MAYBE}; 
exception NO_MEMORY { unsigned long minor; 

completion_status completed; }; 



The completion status value indicates whether the method was never initiated (NO), completed execution prior to the exception (YES), or 
the completion status is indeterminate (MAYBE). 

Since all the standard exceptions have the same structure, file "somcorba.h" (included by "som.h'j defines a generic StExcep typedef which 
can be used instead of the specific typedefs: 



typedef struct StExcep { 




unsigned long minor; 
completion_status completed; 
} StExcep; 



The standard exceptions are defined in an IDL module called StExcep, in the file named "stexcep.idl”, and the C definitions can be found in 
"stexcep.h". 



The Environment 



The Environment is a data structure that contains environmental information that can be passed between a caller and a called object when 
a method is executed. For example, it is used to pass information about the user id of a client, to return exception data to the client following 
a method call, and so on. 

A pointer to an Environment variable is passed as an argument to method calls (unless the method's class has the callstyle=oidl SOM IDL 
modifier). The Environment typedef is defined in "som.h", and an instance of the structure is allocated by the caller in any reasonable way: 
on the stack (by declaring a local variable and initializing it using the macro SOMJnitEnvironment), dynamically (using the 

SOMCreateLocalEnvironment macro), or by calling the somGetGlobalEnvironment function to allocate an Environment structure to be 
shared by objects running in the same thread. 

For class libraries that use callstyle=oidl, there is no explicit Environment parameter. For these libraries, exception information may be 
passed using the per-thread Environment structure returned by the somGetGlobalEnvironment procedure. 



Setting an exception value 



To set an exception value in the caller's Environment structure, a method implementation makes a call to the somSetException 
procedure: 

void somSetException ( Environment *ev, 

except ion_type major , 
string except ion_name , 
void * params) ; 



where "ev" is a pointer to the Environment structure passed to the method, "major" is an exception_type, "exception_name" is the string 
name of the exception (usually the constant defined by the IDL compiler, for example, ex_BAD_FLAG), and "params" is a pointer to an 
(initialized) exception structure which must be allocated bv SOMMalloc : 

typedef enum exception_type { 

NO_EXCEPTION, USER_EXCEPTION, SYSTEM_EXCEPTION 
} exception_type; 



It is important to reiterate that somSetException expects the params argument to be a pointer to a structure that was allocated using 
SOMMalloc. When somSetException is called, the client passes ownership of the exception structure to the SOM run-time environment. 
The SOM run-time environment will free the structure when the exception is reset (that is, upon the next call to somSetException), or when 
the somExceptionFree procedure is called. 

Note that somSetException simply sets the exception value; it performs no exit processing. If there are multiple calls to somSetException 
before the method returns, the caller will only see the last exception value. 



Getting an exception value 



After a method returns, the calling client program can look at the Environment structure to see if there was an exception. The Environment 
struct is mostly opaque, except for an exception type field named _major: 



typedef struct Environment { 




_ma jor ; 



except ion_type 
} Environment; 



If ev._major != NO_EXCEPTION, there was an exception returned by the call. The caller can retrieve the exception name and value 
(passed as parameters in the somSetException call) from an Environment struct via the following functions: 

string somExceptionld (Environment *ei/)\ 
somToken somExceptionValue (Environment 

The somExceptionld function returns the exception name, if any, as a string. The function somExceptionValue returns a pointer to the 
value of the exception, if any, contained in the exception structure. If NULL is passed as the Environment pointer in either of the above 
calls, an implicit call is made to somGetGlobalEnvironment. 

The somExceptionFree procedure will free any memory in the Environment associated with the last exception: 

void somExceptionFree (Environment *ei/); 

If preferred, developers can alternatively use the CORBA "exception_free" API to free the memory in an Environment structure. 

Note: File "somcorba.h" (included by "som.h”) provides the following aliases for strict compliance with CORBA programming interfaces: 

#ifdef CORBA_FUNCTION_NAMES 
♦define exception_id somExceptionld 
♦define exception_value somExceptionValue 
♦define exception_f ree somExceptionFree 
♦endif /* CORBA_FUNCTION_NAMES */ 



Example 



Let us define an IDL interface for a "MyObject" object, which declares a "BAD_FLAG" exception, which can be raised by the 
"checkFlag"method, in a file called "myobject.idl": 

interface MyObject { 

exception BAD_FLAG { long ErrCode; char Reason [80]; } 

void checkFlag(in unsigned long flag) raises (BAD_FLAG) ; 

} ; 



The SOM IDL compiler will map the exception to the following C language constructs, in myobject.h: 

typedef struct BAD_FLAG { 
long ErrCode; 
char Reason [80]; 

} BAD_FLAG; 

#def ine e x_B AD_F LAG "MyObject : : BAD_FLAG" 



A client program that invokes the "checkFlag" method might contain the following error handling code. (Note: The error checking code below 
lies in the user-written procedure, "ErrorCheck," so the code need not be replicated through the program.) 

#include "som.h" 

#include "myobject.h" 

boolean ErrorCheck (Environment *ev) ; /* prototype */ 

main ( ) 

{ 

unsigned long flag; 

Environment ev; 

MyObject myobj; 
char *exld; 

BAD_FLAG *badFlag; 

StExcep *stExValue; 




myobj = MyOb jectNew ( ) ; 
flag = OxOlL; 

SOM_InitEnvironment (&ev) ; 

/* invoke the checkFlag method, passing the Environment param * 
_checkFlag (myobj , &ev, flag); 

/* check for exception */ 
if (ErrorCheck ( &ev) ) 

{ 

/* ... */ 

somExceptionFree ( &ev) ; /* free the exception memory */ 

} 

/* ... */ 



/* error checking procedure */ 
boolean ErrorCheck (Environment *ev) 

{ 

switch (ev._major) 

{ 

case SYSTEM_EXCEPTION : 

/* get system exception id and value */ 
exld = somExceptionld (ev) ; 

stExValue = somExceptionValue (ev) ; 

/* ... */ 
return ( TRUE); 

case USER_EXCEPTION : 

/* get user-defined exception id and value */ 
exld = somExceptionld (ev) ; 
if (strcmp (exld, ex_BAD_FLAG) == 0) 

{ 

badFlag = (BAD_FLAG *) somExceptionValue (ev) ; 
/* ... */ 

} 

/* ... */ 
return ( TRUE) ; 

case NO_EXCEPTION : 
return ( FALSE); 

} 



The implementation of the "checkFlag" method might contain the following error-handling code: 

#include "som.h" 

#include "myobject.h" 

void checkFlag (MyObject somSelf, Environment *ev, 
unsigned long flag) 

{ 

BAD_FLAG *badFlag; 

/* ... */ 

if ( /* flag is invalid */ ) 

{ 

badFlag = (BAD_FLAG *) SOMMalloc (sizeof (BAD_FLAG) ) ; 
badFlag->ErrCode = /* bad flag code */; 
strcpy (badFlag->Reason, "bad flag was passed"); 
somSetException (ev, USER_EXCEPTION, 

ex_BAD_FLAG, (void *) badFlag); 

return ; 

} 

/* ... */ 



Memory management 




The memory management functions used by SOM are a subset of those supplied in the ANSI C standard library. They have the same 
calling interface and the same return types as their ANSI C equivalents, but include supplemental error checking. Errors detected by these 
functions are passed to SOMError (described in the previous section). The correspondence between SOM memory management functions 
and their ANSI C standard library equivalents is shown below: 



SOM FUNCTION 

SOMMalloc 

SOMCalloc 

SOMRealloc 

SOMFree 



EQUIVALENT ANSI C LIBRARY ROUTINE 

malloc 

calloc 

realloc 

free 



SOMMalloc, SOMCalloc, SOMRealloc, and SOMFree are actually g/oba/ variab/es that point to the SOM memory management functions 
(rather than being the names of the functions themselves), so that users can replace them with their own memory management functions if 
desired. (See chapter 5 for a discussion of replacing the SOM memory management functions.) 

C /earing memory for objects 

The memory associated with objects initialized by a client program must also be freed by the client. The SOM-provided method somFree is 
used to release the storage containing the receiver object: 

ftinclude "origcls.h" 

main () 

{ 

OrigCls myObject; 
myObject = OrigClsNew (); 

/* Code to use myObject */ 

_somFree (myObject) ; 

{ 



C/earing memory for the Environment 

Any memory associated with an exception in an Environment structure is typically freed using the somExceptionFree function. (Or, the 
CORBA "exception_free" API can be used.) The somExceptionFree function takes the following form (also see "Example" in the previous 
topic for an application example): 



void somExceptionFree(Environment *ev); 

Note: For information on managing the memory, objects, and exceptions used by DSOM applications, see "Memory management" in 
Chapter 6, "Distributed SOM (DSOM)." 



SOM manipulations using somld's 



A somld is similar to a number that represents a zero-terminated string. A somld is used in SOM to identify method names, class names, 
and so forth. For example, many of the SOM methods that take a method or class name as a parameter require a value of type somld 
rather than string. All SOM manipulations using somlds are case insensitive, although the original case of the string is preserved. 

During its first use with any of the following functions, a somld is automatically converted to an internal representation (registered). Because 
the representation of a somld changes, a special SOM type (somld) is provided for this purpose. Names and the corresponding somld can 
be declared at compile time, as follows: 



string example = "exampleMethodName" ; 
somld exampleld = &example; 




or a somld can be generated at run time, as follows: 

somld myMethodld; 

myMethodld = somldFromString ( "exampleMethodName" ) ; 



SOM provides the following functions that generate or use a somld: 



somldFromString 

somStringFromld 

somComparelds 

somCheckld 

somRegisterld 

somUniqueKey 

somTotalReglds 



Finds the somld that corresponds to a string. The method takes a string as its 
argument, and returns a value of type somld that represents the string. The 
returned somld must later be freed using SOMFree. 

Obtains the string that corresponds to a somld. The function takes a somld as its 
argument and returns the string that the somld represents. 

Determines whether two somld values are the same (that is, represent the same 
string). This function takes two somld values as arguments. It returns TRUE (1) if 
the somlds represent the same string, or FALSE (0) otherwise. 

Determines whether SOM already knows a somld. The function takes a somld as 
its argument. It verifies whether the somld is registered and in normal form, 
registers it if necessary, and returns the input somld. 

The same as somCheckld, except it returns TRUE (1 ) if this is the first time the 
somld has been registered, or FALSE (0) otherwise. 

Finds the unique key for a somld. The function takes a somld identifier as its 
argument, and returns the unique key for the somld-a number that uniquely 
represents the string that the somld represents. This key is the same as the key 
for another somld if and only if the other somld refers to the same string as the 
input somld. 

Finds the total number of somlds that have been registered, as an unsigned 
long. This function is used to determine an appropriate argument to 
somSetExpectedlds, below, in later executions of the program. The function 
takes no input arguments. 



somSetExpectedlds Indicates how many unique somlds SOM can expect to use during program 

execution, which, if accurate, can improve the space and time utilization of the 
program slightly. This routine must be called before the SOM run-time 
environment is initialized (that is, before the function somEnvironmentNew is 
invoked and before any objects are created). This is the only SOM function that 
can be invoked before the SOM run-time environment is initialized. The input 
argument is an unsigned long. The function has no return value. 



somBeginPersistentlds and somEndPersistentlds Delimit a time interval for the current thread during which it is guaranteed that (a) 

any new somlds that are created will refer only to static strings and (b) these 
strings will not be subsequently modified or freed. These functions are useful 
because somlds that are registered within a "persistent ID interval" can be 
handled more efficiently. 



See the System Object Moc/e/ Programming Reference for more information on a specific function. 



SOM IDL and the SOM Compiler 



This chapter first discusses how to define SOM classes and then describes the SOM Compiler. To allow a class of objects to be 
implemented in one programming language and used in another (that is, to allow a SOM class to be language neutral), the interface to 
objects of this class must be specified separately from the objects' implementation. 

To summarize: As a first step, a file known as the .idl file is used to declare classes and their methods, using SOM's language#neutral 
Interface Definition Language (IDL). Next, the SOM Compiler is run on the .idl file to produce a template implementation file that contains 
stub method procedures for the new and overridden methods; this preliminary code corresponds to the computer language that will 
implement the class. Then, the class implementer fills in the stub procedures with code that implements the methods (or redefines 
overridden methods) and sets instance data. (This implementation process is the subject of Chapter 5, "Implementing Classes in SOM.") At 
this point, the implementation file can be compiled and linked with a client program that uses it (as described in Chapter 3, "Using SOM 
Classes in Client Programs"). 




Syntax for SOM IDL and the SOM Compiler are presented in this chapter, along with helpful information for using them correctly. 



Interface vs Implementation 



The interface to a class of objects contains the information that a client must know to use an object-namely, the names of its attributes and 
the signatures of its methods . The interface is described in a formal language independent of the programming language used to implement 
the object's methods. In SOM, the formal language used to define object interfaces is the Interface Definition Language (IDL), 
standardized by CORBA. 

The imp/ementat/on of a class of objects (that is, the procedures that implement methods) is written in the implementer's preferred 
programming language. This language can be object-oriented (for instance, C++) or procedural (for instance, C). 

A completely implemented class definition, then, consists of two main files: 

• An IDL specification of the interface to instances of the class (the interface definition fi/e (or .idl file) and 

• Method procedures written in the implementer's language of choice (the impiementation fi/e). 

The interface definition file has an .idl extension, as noted. The implementation file, however, has an extension specific to the language in 
which it is written. For example, implementations written in C have a .c extension, and implementations written in C++ have a .C (for AIX) or 
.cpp (for OS/2) extension. 

To assist users in implementing SOM classes, the SOMobjects Toolkit provides a SOM Compiler. The SOM Compiler takes as input an 
object interface definition file (the .idl file) and produces a set of binding files that make it convenient to implement and use a SOM class 
whose instances are objects that support the defined interface. The binding files and their purposes are as follows: 

• An impiementation template that serves as a guide for how the implementation file for the class should look. The class 
implementer fills in this template file with language-specific code to implement the methods that are available on the class' 
instances. 

• Header fi/es to be included (a) in the class's implementation file and (b) in client programs that use the class. 

These binding files produced by the SOM Compiler bridge the gap between SOM and the object model used in object-oriented languages 
(such as C++), and they allow SOM to be used with non-object-oriented languages (such as C). The SOM Compiler currently produces 
binding files for the C and C++ programming languages. SOM can also be used with other programming languages; the bindings simply 
offer a more convenient programmer's interface to SOM. Vendors of other languages may also offer SOM bindings; check with your 
language vendor for possible SOM support. 

The subsequent sections of this chapter provide full syntax for SOM IDL and the SOM Compiler. 



SOM Interface Definition Language 



This section describes the syntax of SOM's Interface Definition Language (SOM IDL). SOM IDL complies with CORBA's standard for IDL; 
it also adds constructs specific to SOM. (For more information on the CORBA standard for IDL, see The Common Object Request Broker: 
Architecture and Specification , published by Object Management Group and x/Open.) The full grammar for SOM IDL is given in Appendix 
C. Instructions for converting existing OIDL-syntax files to IDL are given in Appendix B. The current section describes the syntax and 
semantics of SOM IDL using the following conventions: 

Constants (words to be used literally, such as keywords) appear in bold. 

User-supplied elements appear in italics. 

{ } Groups related items together as a single item. 

[ ] Encloses an optional item. 

* Indicates zero or more repetitions of the preceding item. 

+ Indicates one or more repetitions of the preceding item. 

| Separates alternatives. 

_ Within a set of alternatives, an underscore indicates the default, if defined. 




IDL is a formal language used to describe object interfaces. Because, in SOM, objects are implemented as instances of classes, an IDL 
object interface definition specifies for a class of objects what methods (operations) are available, their return types, and their parameter 
types. For this reason, we often speak of an IDL specification for a class (as opposed to simply an object interface). Constructs specific to 
SOM discussed below further strengthen this connection between SOM classes and the IDL language. 

IDL generally follows the same lexical rules as C and C++, with some exceptions. In particular: 

• IDL uses the ISO Latin-1 (8859.1) character set (as per the CORBA standard). 

• White space is ignored except as token delimiters. 

• C and C++ comment styles are supported. 

• IDL supports standard C/C++ preprocessing, including macro substitution, conditional compilation, and source file inclusion. 

• Identifiers (user-defined names for methods, attributes, instance variables, and so on) are composed of alphanumeric and 
underscore characters, (with the first character alphabetic) and can be of arbitrary length, up to an operating-system limit of 
about 250 characters. 

• Identifiers must be spelled consistently with respect to case throughout a specification. 

• Identifiers that differ only in case yield a compilation error. 

• There is a single name space for identifiers (thus, using the same identifier for a constant and a class name within the same 
naming scope, for example, yields a compilation error). 

• Integer, floating point, character, and string literals are defined just as in C and C++. 

The terms listed in the Keywords table are reserved keywords and may not be used otherwise. Keywords must be spelled using upper- and 
lower-case characters exactly as shown in the table. For example, ''void 1 ' is correct, but "Void" yields a compilation error. 

A typical IDL specification for a single class, residing in a single .idl file, has the following form. (Also see the later section, "Module 
declarations to define multiple interfaces in an .idl file.") The order is unimportant, except that names must be declared (or forward 
referenced) before they are referenced. The subsequent topics of this section describe the requirements for these specifications: 



Include directives (optional) 

Type declarations (optional) 

Constant declarations (optional) 

Exception declarations (optional) 

Interface declaration (optional) 

Module declaration (optional) 



Keywords for SOM IDL 



any 


FALSE 


readonly 


attribute 


float 


sequence 


boolean 


implementation 


short 


case 


in 


string 


char 


inout 


struct 


class 


interface 


switch 


const 


long 


TRUE 


context 


module 


TypeCode 


default 


octet 


typedef 


double 


oneway 


unsigned 


enum 


out 


union 


exception 


raises 


void 




Include directives 



The IDL specification for a class normally contains #include statements that tell the SOM Compiler where to find the interface definitions 
(the .idl files) for: 

• Each of the class's parent (direct base) classes, and 

• The class's metaclass (if specified). 

The #include statements must appear in the above order. For example, if class "C" has parents "foo" and "bar" and metaclass "meta", then 
file "C.idl" must begin with the following #include statements: 

ftinclude <foo.idl> 
ftinclude <bar.idl> 
ftinclude <meta.idl> 



As in C and C++, if a filename is enclosed in angle brackets (< >), the search for the file will begin in system-specific locations. If the 
filename appears in double quotation marks (" "), the search for the file will begin in the current working directory, then move to the 
system-specific locations. 



Type and constant declarations 



IDL specifications may include type declarations and constant declarations as in C and C++, with the restrictions/extensions described 
below. [Note: For any reader not familiar with C, a recommended reference is The C Programm/hg Language (2nd edition, 1 988, Prentice 
Flail) by Brian W. Kernighan and Dennis M. Ritchie. See pages 36-40 for a discussion of type and constant declarations.] 

IDL supports the following basic types (these basic types are also defined for C and C++ client and implementation programs, using the 
SOM bindings): 



Integral types 



IDL supports only the integral types short, long, unsigned short, and unsigned long, which represent the following value ranges: 



short 

long 

unsigned short 
unsigned long 



-2[1 5] .. 2[15]-1 
-2[31] .. 2[31]-1 
0 .. 2[16]-1 
0 .. 2[32]-1 



Floating point types 



IDL supports the float and double floating-point types. The float type represents the IEEE single-precision floating-point numbers; double 
represents the IEEE double-precision floating-point numbers. 



Character type 




IDL supports a char type, which represents an 8-bit quantity. The ISO Latin-1 (8859.1) character set defines the meaning and 
representation of graphic characters. The meaning and representation of null and formatting characters is the numerical value of the 
character as defined in the ASCII (ISO 646) standard. Unlike C/C++, type char cannot be qualified as signed or unsigned. (The octet type, 
below, can be used in place of unsigned char.) 



Boolean type 



IDL supports a boolean type for data items that can take only the values TRUE and FALSE. 



Octet type 



IDL supports an octet type, an 8-bit quantity guaranteed not to undergo conversion when transmitted by the communication system. The 
octet type can be used in place of the unsigned char type. 



Any type 



IDL supports an any type, which permits the specification of values of any IDL type. In the SOM C and C++ bindings, the any type is 
mapped onto the following struct: 

typedef struct any { 

TypeCode _type; 
void *_value; 

} any; 



The ”_value" member for an any type is a pointer to the actual value. The "_type" member is a pointer to an instance of a TypeCode that 
represents the type of the value. The TypeCode provides functions for obtaining information about an IDL type. Chapter 7, "The Interface 
Repository Framework,” describes TypeCodes and their associated functions. 



Constructed types 



In addition to the above basic types, IDL also supports three constructed types: struct, union, and enum. The structure and enumeration 
types are specified in IDL the same as they are in C and C++ [Kernighan-Ritchie references: struct, p. 128; union, p. 147; enum, p. 39], with 
the following restrictions: 

Unlike C/C++, recursive type specifications are allowed only through the use of the sequence template type (see below). 

Unlike C/C++, structures, discriminated unions, and enumerations in IDL must be tagged. For example, "struct { int a; ... }" is an 
invalid type specification. The tag introduces a new type name. 

In IDL, constructed type definitions need not be part of a typedef statement; furthermore, if they are part of a typedef statement, 
the tag of the struct must differ from the type name being defined by the typedef. For example, the following are valid IDL struct 
and enum definitions: 

struct myStruct { 
long x; 
double y; 

}; /* defines type name myStruct* / 



enum colors { red, white, blue } ; /* defines type name colors */ 




By contrast, the following definitions are not valid: 



typedef struct myStruct { /* NOT VALID */ 

long x; 
double y; 

} myStruct; /* myStruct has been redefined */ 

typedef enum colors { red, white, blue } colors; /* NOT VALID */ 



The valid IDL struct and enum definitions shown above are translated by the SOM Compiler into the following definitions in the C and C++ 
bindings, assuming they were declared within the scope of interface "Hello": 

typedef struct Hello_myStruct { /* C/C++ bindings for IDL struct */ 

long x; 
double y; 

} Hello_myStruct; 

typedef unsigned long Hello_colors ; /* C/C++ bindings for IDL enum */ 

#define Hello_red 1UL 
#define Hello_white 2UL 
#define Hello_blue 3UL 



When an enumeration is defined within an interface statement for a class, then within C/C++ programs, the enumeration names must be 
referenced by prefixing the class name. For example, if the co/ors enum, above, were defined within the interface statement for class He/Zo, 
then the enumeration names would be referenced as Z/eZ/o_recZ, Z/e//o_wZiZte , and He//o_b/ue . Notice the first identifier in an enumeration is 
assigned the value 1 . 

All types and constants generated by the SOM Compiler are fuZ/y qua/ifiecZ . That is, prepended to them is the fully qualified name of the 
interface or module in which they appear. For example, consider the following fragment of IDL: 

module M { 

typedef long long_t; 
module N { 

typedef long long_t; 
interface I { 

typedef long long_t; 




}; 



That specification would generate the following three types: 



typedef long 
typedef long 
typedef long 



M_long_t ; 
M_N_long_t ; 
M_N_I_long_t ; 



For programmer convenience, the SOM Compiler also generates shorter bindings, without the interface qualification. Consider the next IDL 
fragment: 

module M { 

typedef long long_t; 
module N { 

typedef short short_t; 
interface I { 

typedef char char_t; 




}; 



In the C/C++ bindings of the preceding fragment, you can refer to "M_long_t" as "long_t", to "M_N_short_t" as "short_t", and to 
"M_N_l_char_t" as ”char_t". 

However, these shorter forms are available on/y when their interpretation is not ambiguous. Thus, in the first example the shorthand for 
"M_N_l_long_t" would not be allowed, since it clashes with "M_long_t" and "M_N_long_t". If these shorter forms are not required, they can 
be ignored by setting #define SOM_DONT_USE_SHORT_NAMES before including the public header files, or by using the SOM 
Compiler option -mnouseshort so that they are not generated in the header files. 




In the SOM documentation and samples, both long and short forms are illustrated, for both type names and method calls. It is the 
responsibility of each user to adopt a style according to personal preference. It should be noted, however, that CORBA specifies that only 
the long forms must be present. 



Union type 



IDL also supports a union type, which is a cross between the C union and switch statements. The syntax of a union type declaration is as 
follows: 

union identifier switch ( switch-type ) 

{ case+ } 

The "identifier" following the union keyword defines a new legal type. (Union types may also be named using a typedef declaration.) The 
"switch-type” specifies an integral, character, boolean, or enumeration type, or the name of a previously defined integral, boolean, character, 
or enumeration type. Each "case" of the union is specified with the following syntax: 

case-/abe/+ type-spec declarator ; 

where "type-spec" is any valid type specification; "declarator" is an identifier, an array declarator (such as, f oo [ 3 ] [ 5 ] ), or a pointer 
declarator (such as, *f oo); and each "case-label" has one of the following forms: 

case const-expr. 

default: 

The "const-expr" is a constant expression that must match or be automatically castable to the "switch-type". A default case can appear no 
more than once. 

Unions are mapped onto C/C++ structs. For example, the following IDL declaration: 

union Foo switch (long) { 
case 1 : long x; 
case 2: float y; 
default: char z; 

}; 



is mapped onto the following C struct: 

typedef Hello_struct { 
long _d; 
union { 
long x; 
float y; 
char z; 

} _u; 

} Hello_foo; 



The discriminator is referred to as "_d", and the union in the struct is referred to as ”_u". Flence, elements of the union are referenced just as 
in C: 

Foo v; 

/* get a pointer to Foo in v: */ 
switch (v->_d) { 

case 1: printf("x = %ld\n", v->_u.x); break; 
case 2: printf("y = %f\n", v->_u.y); break; 
default: printf("z = %c\n", v->_u.z); break; 

} 



Note: This example is from The Common Object Request Broker: Architecture and Specification, revision 1 .1 , page 90. 



Template types (sequences and strings) 




IDL defines two template types not found in C and C++: sequences and strings. A sequence is a one-dimensional array with two 
characteristics: a maximum size (specified at compile time) and a length (determined at run time). Sequences permit passing unbounded 
arrays between objects. Sequences are specified as follows: 

sequence < s/mp/e-type [, pos/t/ve-/nteger-consf\ > 

where "simple-type" specifies any valid IDL type, and the optional "positive-integer-const" is a constant expression that specifies the 
maximum size of the sequence (as a positive integer). 

Note: The "simple-type" cannot have a directly in the sequence statement. Instead, a typedef for the pointer type must be used. For 
example, instead of: 

typedef sequence<long *> seq_longptr; // Error: not allowed. 



use: 

typedef long * longptr; 

typedef sequence<longptr> seq_longptr; // Ok. 



In SOM's C and C++ bindings, sequences are mapped onto structs with the following members: 

unsigned long maximum; 
unsigned long length; 

s/mp/e-type *_buffer; 

where "simple-type" is the specified type of the sequence. For example, the IDL declaration 

typedef sequence<long, 10> veclO; 



results in the following C struct: 

#if ndef _IDL_SEQUENCE_long_de fined 
#def ine _IDL_SEQUENCE_long_de fined 
typedef struct { 

unsigned long _maximum; 
unsigned long ^length; 
long *_buffer; 

} _IDL_SEQUENCE_long; 

#endif /* _IDL_SEQUENCE_long_de fined */ 
typedef _IDL_SEQUENCE_long veclO; 



and an instance of this type is declared as follows: 

veclO v = {10L, OL, (long *)NULL}; 



The "_maximum" member designates the actual size of storage allocated for the sequence, and the "Jength" member designates the 
number of values contained in the ”_buffer" member. For bounded sequences, it is an error to set the "Jength" or "_maximum" member to 
a value larger than the specified bound of the sequence. 

Before a sequence is passed as the value of an "in" or "inout" method parameter, the ’Jbuffer" member must point to an array of elements 
of the appropriate type, and the "Jength” member must contain the number of elements to be passed. (If the parameter is "inout" and the 
sequence is unbounded, the "_maximum" member must also be set to the actual size of the array. Upon return, "Jength" will contain the 
number of values copied into Jbuffer", which must be less than Jmaximum".) When a sequence is passed as an "out" method parameter 
or received as the return value, the method procedure allocates storage for Jbuffer" as needed, the "Jength" member contains the number 
of elements returned, and the Jmaximum" member contains the number of elements allocated. (The client is responsible for subsequently 
freeing the memory pointed to by Jbuffer".) 

C and C++ programs using SOM's language bindings can refer to sequence types as: 

JDL_SEQUENCE_*Z76> 

where "type" is the effective type of the sequence members. For example, the IDL type sequence<long, 10> is referred to in a 
C/C++ program by the type name _IDL_SEQUENCE_long . If longint is defined via a typedef to be type long, then the IDL 
type sequence<longint , 1 0> is also referred to by the type name _IDL_SEQUENCE_long. 

If the typedef is for a pointer type, then the effective type is the name of the pointer type. For example, the following statements define a 
C/C++ type _IDL_SEQUENCE_longptr and /7c>/_IDL_SEQUENCE_long : 




typedef long * longptr; 

typedef sequence<longptr> seq_longptr; 



A string is similar to a sequence of type char. It can contain all possible 8-bit quantities except NULL. Strings are specified as follows: 
string [ < positive-integer-const > ] 

where the optional ''positive-integer-const" is a constant expression that specifies the maximum size of the string (as a positive integer, 
which does not include the extra byte to hold a NULL as required in C/C++). In SOM's C and C++ bindings, strings are mapped onto 
zero-byte terminated character arrays. The length of the string is encoded by the position of the zero-byte. For example, the following IDL 
declaration: 

typedef string<10> foo; 

is converted to the following C/C++ typedef: 

typedef char *foo; 

A variable of this type is then declared as follows: 

foo s = (char *) NULL; 

C and C++ programs using SOM's language bindings can refer to string types by the type name string. 

When an unbounded string is passed as the value of an "inout 1 ' method parameter, the returned value is constrained to be no longer than 
the input value. Hence, using unbounded strings as "inout" parameters is not advised. 



Arrays 



Multidimensional, fixed-size arrays can be declared in IDL as follows: 
identifier {[ positive-integer-const ] }+ 

where the "positive-integer-const" is a constant expression that specifies the array size, in each dimension, as a positive integer. The array 
size is fixed at compile time. 



Pointers 



Although the CORBA standard for IDL does not include them, SOM IDL offers pointer types. Declarators of a pointer type are specified as in 
C and C++: 

type 'declarator 

where "type" is a valid IDL type specification and "declarator" is an identifier or an array declarator. 



Object types 



The name of the interface to a class of objects can be used as a type. For example, if an IDL specification includes an interface declaration 
(described below) for a class (of objects) "Cl ", then ”C1 " can be used as a type name within that IDL specification. When used as a type, an 
interface name indicates a pointer to an object that supports that interface. An interface name can be used as the type of a method 
argument, as a method return type, or as the type of a member of a constructed type (a struct, union, or enum). In all cases, the use of an 
interface name implicitly indicates a pointer to an object that supports that interface. 




As explained in Using SOM Classes in Client Programs, SOM's C usage bindings for SOM classes also follow this convention. However, 
within SOM's C++ bindings, the pointer is made explicit, and the use of an interface name as a type refers to a class instance itself, rather 
than a pointer to a class instance. For example, to declare a variable "myobj" that is a pointer to an instance of class "Foo" in an IDL 
specification and in a C program, the following declaration is required: 

Foo myobj; 

However, in a C++ program, the following declaration is required: 

Foo *myobj; 

If a C programmer uses the SOM Compiler option -maddstar, then the bindings generated for C will also require an explicit in 
declarations. Thus, 

Foo myobj; in IDL requires 

Foo *myobj; in both C and C++ programs 

This style of bindings for C is permitted for two reasons: 

• It more closely resembles the bindings for C++, thus making it easier to change to the C++ bindings at a later date; and 

■ It is required for compatibility with existing SOM OIDL code. 

Note: The same C and C++ binding emitters should not be run in the same SOM Compiler command. For example, 

sc "~sh;xh" cls.idl // Not valid. 

If you wish to generate both C and C++ bindings, you should issue the commands separately: 

sc -sh cls.idl 
sc -sxh cls.idl 



Exception declarations 



IDL specifications may include exception declarations, which define data structures to be returned when an exception occurs during the 
execution of a method. (IDL exceptions are implemented by simply passing back error information after a method call, as opposed to the 
"catch/throw" model where an exception is implemented by a long jump or signal.) Associated with each type of exception is a name and, 
optionally, a struct-like data structure for holding error information. Exceptions are declared as follows: 

exception identifier { member * }; 

The ''identifier” is the name of the exception, and each "member" has the following form: 
type-spec dec/arators ; 

where "type-spec" is a valid IDL type specification and "declarators" is a list of identifiers, array declarators, or pointer declarators, delimited 
by commas. The members of an exception structure should contain information to help the caller understand the nature of the error. The 
exception declaration can be treated like a struct definition; that is, whatever you can access in an IDL struct, you can access in an 
exception declaration. Alternatively, the structure can be empty , whereby the exception is just identified by its name. 

If an exception is returned as the outcome of a method, the exception "identifier" indicates which exception occurred. The values of the 
members of the exception provide additional information specific to the exception. The topic "Method declarations" below describes how to 
indicate that a particular method may raise a particular exception, and Using SOM Classes in Client Programs, describes how exceptions 
are handled, in the section entitled "Exceptions and error handling." 

Following is an example declaration of a "BAD_FLAG" exception: 



exception BAD_FLAG { long ErrCode; char Reason[80]; }; 



The SOM Compiler will map the above exception declaration to the following C language constructs: 



#def ine ex_BAD_FLAG " : : BAD_FLAG" 
typedef struct BAD_FLAG { 
long ErrCode; 
char Reason [80] ; 

} BAD_FLAG; 



Thus, the ex_BAD_FLAG symbol can be used as a shorthand for naming the exception. 
An exception declaration within an interface "Hello", such as this: 

interface Hello { 

exception LOCAL_EXCEPTION { long ErrCode; }; 

} ; 



would map onto: 

#def ine ex_Hello_LOCAL_EXCEPTION Hello :: LOCAL_EXCEPTION" 

typedef struct Hello_LOCAL_EXCEPTION { 
long ErrCode; 

} Hello_LOCAL_EXCEPTION; 

#def ine ex_LOCAL_EXCEPTION ex_Hello_LOCAL_EXCEPTION 



In addition to user-defined exceptions, there are several predefined exceptions for system run-time errors. The standard exceptions as 
prescribed by CORBA are shown in the table "Standard Exceptions Defined by CORBA". These exceptions correspond to standard run-time 
errors that may occur during the execution of any method (regardless of the list of exceptions listed in its IDL specification). 

Each of the standard exceptions has the same structure: an error code (to designate the subcategory of the exception) and a completion 
status code. For example, the NO_MEMORY standard exception has the following definition: 

enum completion_status {YES, NO, MAYBE}; 
exception NO_MEMORY { unsigned long minor; 

completion_status completed; }; 



The ''completion_status" value indicates whether the method was never initiated (NO), completed its execution prior to the exception (YES), 
or the completion status is indeterminate (MAYBE). 

Since all the standard exceptions have the same structure, somcorba.h (included by som.h) defines a generic StExcep typedef which can 
be used instead of the specific typedefs: 

typedef struct StExcep { 
unsigned long minor; 
completion_status completed; 

} StExcep; 



The standard exceptions shown in the table "Standard Exceptions Defined by CORBA". are defined in an IDL module called StExcep, in the 
file called stexcep.idl, and the C definitions can be found in stexcep.h. 



Standard Exceptions Defined by CORBA 

module StExcep { 

#define ex_body { unsigned long minor; completion_status completed; } 
enum completion_status { YES, NO, MAYBE }; 



enum exception_type {NO_EXCEPTION, USER_EXCEPTION, SYSTEM_EXCEPTION } ; 



exception 


UNKNOWN 


ex_body 


exception 


BAD_PARAM 


ex_body 


exception 


NO_MEMORY 


ex_body 


exception 


IMP_LIMIT 


ex_body 


exception 


COMM_F AI LURE 


ex_body 


exception 


INV_OB JREF 


ex_body 


exception 


NO_PERMISSION 


ex_body 


exception 


INTERNAL 


ex_body 


exception 


MARSHAL 


ex_body 


exception 


INITIALIZE 


ex_body 


exception 


NO_IMPLEMENT 


ex_body 



// the unknown exception 

// an invalid parameter was passed 

// dynamic memory allocation failure 

// violated implementation limit 

// communication failure 

// invalid object reference 

// no permission for attempted op. 

// ORB internal error 
// error marshalling param/result 
// ORB initialization failure 
// op. implementation unavailable 




exception 


BAD_TYPECODE 


ex_body; 


exception 


BAD_OPERATION 


ex_body; 


exception 


NO_RE SOURCES 


ex_body; 

request 


exception 


NO_RESPONSE 


ex_body; 

available 


exception 


PERSIST_STORE 


ex_body; 


exception 


BAD_INV_ORDER 


ex_body; 
of order 


exception 


TRANSIENT 


ex_body; 

request 


exception 


FREE_MEM 


ex_body; 


exception 


INV_IDENT 


ex_body; 


exception 


INV_FLAG 


ex_body; 


exception 


INTF_REPOS 


ex_body; 

repository 


exception 


CONTEXT 


ex_body; 


exception 


OB J_ADAPTER 


ex_body; 


exception 


DATA_CONVERSION 


ex_body; 



// bad typecode 

// invalid operation 

// insufficient resources for 

// response to req. not yet 

// persistent storage failure 
// routine invocations out 

// transient failure - reissue 

// cannot free memory 
// invalid identifier syntax 
// invalid flag was specified 
// error accessing interface 

// error processing context object 
// failure detected by object adapter 
// data conversion error 



Interface declarations 



The IDL specification for a class of objects must contain a declaration of the interface these objects will support. Because, in SOM, objects 
are implemented using classes, the interface name is always used as a class name as well. Therefore, an interface declaration can be 
understood to specify a class name, and its parent (direct base) class names. This is the approach used in the following description of an 
interface declaration. In addition to the class name and its parents names, an interface indicates new methods (operations), and any 
constants, type definitions, and exception structures that the interface exports. An interface declaration has the following syntax: 
interface class-name [: parent-classi, parent-class2, ...] 

{ 



constant dec/a ratio ns 
type dec/a rations 
exception dec/a ratio ns 
attribute dec/a ratio ns 
method declarations 
implementation statement 



(optional) 

(optional) 

(optional) 

(optional) 

(optional) 

(optional) 



}; 



Many class implementers distinguish a "class-name" by using an initial capital letter, but that is optional. The "parent-class" (or base-class) 
names specify the interfaces from which the interface of "class-name" instances is derived. Parent-class names are required only for the 
immediate parent(s). Each parent class must have its own IDL specification (which must be dinc/ude d in the subclass's .idl file). A parent 
class cannot be named more than once in the interface statement header. 

Note: In general, an "interface class-name" header must precede any subsequent implementation that references "class-name." For more 
discussion of multiple interface statements, refer to the later topic "Module declarations to define multiple interfaces in an .idl file." 

The following topics describe the various declarations/statements that can be specified within the body of an interface declaration. The 
order in which these declarations are specified is usually optional, and declarations of different kinds can be intermixed. Although all of the 
declarations/statements are listed above as "optional," in some cases using one of them may mandate another. For example, if a method 
raises an exception, the exception structure must be defined beforehand. In general, types, constants, and exceptions, as well as 
interface declarations, must be defined before they are referenced, as in C/C++. 



Constant, type, and exception declarations 



The form of a constant, type, or exception declaration within the body of an interface declaration is the same as described previously in 
this chapter. Constants and types defined within an interface for a class are transferred by the SOM Compiler to the binding files it 
generates for that class, whereas constants and types defined outside of an interface are not. 

Global types (such as, those defined outside of an interface and module) can be emitted by surrounding them with the following #pragmas: 

#pragma somemittypes on 

typedef sequence <long, 10> veclO; 




exception BAD_FLAG { long ErrCode; char Reason[80]; }; 
typedef long long_t; 

♦pragma somemittypes off 



Types, constants, and exceptions defined in a parent class are also accessible to the child class. References to them, however, must be 
unambiguous. Potential ambiguities can be resolved by prefacing a name with the name of the class that defines it, separated by the 
characters as illustrated below: 



MyParentClass : :myType 



The child class can redefine any of the type, constant, and exception names that have been inherited, although this is not advised. The 
derived class cannot, however, redefine attributes or methods. It can only replace the implementation of methods through overriding (as in 
example 3 of the Tutorial). To refer to a constant, type, or exception "name" defined by a parent class and redefined by "class-name," use 
the "parent-name::name" syntax as before. 

Note: A name reference such as MyParentClass : : myType required in IDL syntax is equivalent to 

MyParentClass_myType in C/C++. For a full discussion of name recognition in SOM, see "Scoping and name resolution" later in 
this chapter. 



Attribute declarations 



Declaring an attribute as part of an interface is equivalent to declaring two accessor methods: one to retrieve the value of the attribute (a 
"get" method, named "_get_<attributeName>”) and one to set the value of the attribute (a "set" method, named "_set_<attributeName>"). 

Attributes are declared as follows: 

[ readonly ] attribute type-spec declarators ; 

where "type-spec" specifies any valid IDL type and "declarators" is a list of identifiers or pointer declarators, delimited by commas. (An array 
declarator cannot be used directly when declaring an attribute, but the type of an attribute can be a user-defined type that is an array.) The 
optional readonly keyword specifies that the value of the attribute can be accessed but not modified by client programs. (In other words, a 
readonly attribute has no "set" method.) Below are examples of attribute declarations, which are specified within the body of an interface 
statement for a class: 

interface Goodbye: Hello, SOMObject 
{ 

void sayBye ( ) ; 

attribute short xpos; 
attribute char cl, c2; 
readonly attribute float xyz; 

} ; 



The preceding attribute declarations are equivalent to defining the following methods: 



short 


_get_xpos ( ) ; 


void 


_set_xpos (in short xpos) 


char 


_get_cl ( ) ; 


void 


_set_cl (in char cl) ; 


char 


_get_c2 ( ) ; 


void 


_set_c2 (in char c2); 


float 


_get_xyz ( ) ; 



Note: Although the preceding attribute declarations are equivalent to the explicit method declarations above, these method declarations are 
not legal IDL, because the method names begin with an All IDL identifiers must begin with an alphabetic character, not including 

Attributes are inherited from ancestor classes (indirect base classes). An inherited attribute name cannot be redefined to be a different 
type. 



Method (operation) declarations 




Method (operation) declarations define the interface of each method introduced by the class. A method declaration is similar to a C/C++ 
function definition: 

[oneway] type-spec identifier ( parameter-list) 

[ra/ses-expr\ \context-expr\ ; 

where "identifier" is the name of the method and "type-spec" is any valid IDL type (or the keyword void, indicating that the method returns 
no value). Unlike C and C++ procedures, methods that do not return a result must specify void as their return type. The remaining syntax of 
a method declaration is elaborated in the following subtopics. 

Note: Although IDL does not allow methods to receive and return values whose type is a pointer to a function, it does allow methods to 
receive and return method names fas string values). Thus, rather than defining methods that pass pointers to functions (and that 
subsequently invoke those functions), programmers should instead define methods that pass method names (and subsequently invoke 
those methods using one of the SOM-supplied method-dispatching or method-resolution methods or functions, such as somDispatch). 



Oneway keyword 



The optional oneway keyword specifies that when a client invokes the method, the invocation semantics are "best-effort", which does not 
guarantee delivery of the call. "Best-effort" implies that the method will be invoked at most once. A oneway method should not have any 
output parameters and should have a return type of void. A oneway method also should not include a "raises expression" (see below), 
although it may raise a standard exception. 

If the oneway keyword is not specified, then the method has "at-most-once" invocation semantics if an exception is raised, and it has 
"exactly-once" semantics if the method succeeds. This means that a method that raises an exception has been executed zero or one times, 
and a method that succeeds has been executed exactly once. 

Note: Currently the "oneway" keyword, although accepted, has no effect on the C/C++ bindings that are generated. 



Parameter list 



The "parameter-list" contains zero or more parameter declarations for the method, delimited by commas. (The target object for the method is 
not explicitly specified as a method parameter in IDL, nor are the Environment or Context parameters.) If there are no explicit parameters, 
the syntax "( )" must be used, rather than "(void)". A parameter declaration has the following syntax: 

{ in PE out PE inout } type-spec declarator 

where "type-spec" is any valid IDL type and "declarator" is an identifier, array declarator, or pointer declarator. 

In. out, inout parameters: The required in/Eout/Einout directional attribute indicates whether the parameter is to be passed from client to 
server (in), from server to client (out), or in both directions (inout). A method must not modify an in parameter. If a method raises an 
exception, the values of the return result and the values of the out and inout parameters (if any) are undefined. When an unbounded string 
or sequence is passed as an inout parameter, the returned value must be no longer than the input value. 

The following are examples of valid method declarations in SOM IDL: 

short methl (in char c, out float f ) ; 
oneway void meth2 (in char c) ; 
float meth3(); 



Classes derived from SOMObject can declare methods that take a pointer to a block of memory containing a variable number of arguments, 
using a final parameter of type vajist. The vajist must use the parameter name "ap", as in the following example: 

void MyMethod(in short numArgs, in va_list ap) ; 



For in parameters of type array, C and C++ clients must pass the address of the first element of the array. For in parameters of type struct, 
union, sequence or any, C/C++ clients must pass the address of a variable of that type, rather than the variable itself. 

For all IDL types except arrays, if a parameter of a method is out or inout, then C/C++ clients must pass the address of a variable of that 
type (or the value of a pointer to that variable) rather than the variable itself. (For example, to invoke method "methl" above, a pointer to a 
variable of type float must be passed in place of parameter "f".) For arrays, C/C++ clients must pass the address of the first element of the 




array. 



If the return type of a method is a struct, union, sequence, or any type, then for C/C++ clients, the method returns the value of the C/C++ 
struct representing the IDL struct, union, sequence, or any. If the return type is string, then the method returns a pointer to the first 
character of the string. If the return type is array, then the method returns a pointer to the first element of the array. 

The pointers implicit in the parameter types and return types for IDL method declarations are made explicit in SOM's C and C++ bindings. 
Thus, the stub procedure that the SOM Compiler generates for method "methl”, above, has the following signature: 

SOM_Scope short SOMLINK methl (char c, float *f ) 



For C and C++ clients, if a method has an out parameter of type string sequence, or any, then the method must allocate the storage for 
the string, for the "_buffer" member of the struct that represents the sequence, or for the "_value” member of the struct that represents the 
any. It is then the responsibility of the client program to free the storage when it is no longer needed. Similarly, if the return type of a method 
is string, sequence, array, or any, then storage must be allocated by the method, and it will be the responsibility of the client program to 
subsequently free it. 

Note: The foregoing description also applies for the _get_ <attribute/\/ame> method associated with an attribute of type string, sequence, 
any, or array. Flence, the attribute should be specified with a "noget" modifier to override automatic implementation of the attribute's "get” 
method. Then, needed memory can be allocated by the developer's "get" method implementation and subsequently deallocated by the 
caller. (The "noget" modifier is described under the topic "Modifier statements" later in this section.) 



Raises expression 



The optional raises expression ("raises-expr") in a method declaration indicates which exceptions the method may raise. (IDL exceptions 
are implemented by simply passing back error information after a method call, as opposed to the "catch/throw" model where an exception is 
implemented by a long jump or signal.) A raises expression is specified as follows: 

raises ( identifierf, identified , ... ) 

where each "identifier" is the name of a previously defined exception. In addition to the exceptions listed in the raises expression, a method 
may also signal any of the standard exceptions. Standard exceptions, however, should not appear in a raises expression. If no raises 
expression is given, then a method can raise only the standard exceptions. (See the earlier topic "Exception declarations" for information on 
defining exceptions and for the list of standard exceptions. See Chapter 3, the section entitled "Exceptions and error handling," for 
information on using exceptions.) 



Context expression 



The optional context expression ("context-expr") in a method declaration indicates which elements of the client's context the method may 
consult. A context expression is specified as follows: 

context ( identifieri , identified, ... ) 

where each "identifier" is a string literal made up of alphanumeric characters, periods, underscores, and asterisks. (The first character must 
be alphabetic, and an asterisk can only appear as the last character, where it serves as a wildcard matching any characters. If convenient, 
identifiers may consist of period-separated valid identifier names, but that form is optional.) 

The Context is a special object that is specified by the CORBA standard. It contains a properly list - a set of property-name/string-value 
pairs that the client can use to store information about its environment that methods may find useful. It is used in much the same way as 
environment variables. It is passed as an additional (third) parameter to CORBA-compliant methods that are defined as "context-sensitive" 
in IDL, along with the CORBA-defined Environment structure. 

The context expression of a mehod declaration in IDL specifies which property names the method uses. If these properties are present in 
the Context object supplied by the client, they will be passed to the object implementation, which can access them via the get_values 
method of the Context object. Flowever, the argument that is passed to the method having a context expression is a Context object, not the 
names of the properties. The client program must either create a Context object and use the set_values or set_one_value method of the 
Context class to set the context properties, or use the get_default_context method. The client program then passes the Context object in 
the method invocation. Note that the CORBA standard also allows properties in addition to those in the context expression to be passed in 
the Context object. 

In Chapter 3, "Using SOM Classes in Client Programs,” the topic "Invoking Methods" describes the placement of a context parameter in a 




method call. See also Chapter 6 of The Common Object Request Broker: Architecture and 'Specification for a discussion of how clients 
associate values with context identifiers. A description of the Context class and its methods is contained in the SOMobJects Deve/oper 
Too/k/t: Programmers Reference Manuat. 



Implementation statements 



A SOM IDL interface statement for a class may contain an implementation statement, which specifies information about how the class will 
be implemented (version numbers for the class, overriding of inherited methods, what resolution mechanisms the bindings for a particular 
method will support, and so forth). If the implementation statement is omitted, default information is assumed. 

Because the implementation statement is specific to SOM IDL (and is not part of the CORBA standard), the implementation statement 

should be preceded by an "#ifdef SOMIDL " directive and followed by an "#endif" directive. (See Example 3 in the SOM IDL Tutorial 

presented earlier.) 

The syntax for the implementation statement is as follows: 

#ifdef SOMIDL 

implementation 

f 

impl ementation* 

}; 

#endif 



where each "implementation" can be a modifier statement, a passthru statement, or a declarator of an instance variable, terminated by a 
semicolon. These constructs are described below. An interface statement may not contain multiple implementation statements. 



Modifier statements 



A modifier statement gives additional implementation information about IDL definitions, such as interfaces, attributes, methods, and 
types. Modifiers can be unqualified or qualified: An unqualified modifier is associated with the interface it is defined in. An unqualified 
modifier statement has the following two syntactic forms: 

modifier 

modifier = va/ue 

where "modifier" is either a SOM Compiler-defined identifier or a user-defined identifier, and where "value" is an identifier, a string enclosed 
in double quotes (" "), or a number. 

For example: 

filestem = foo; 

nodata; 

persistent; 

dllname = "E : /som/dlls" ; 



A qualified modifier is associated with a qualifier . The qualified modifier has the syntax: 

qualifier : modifier 
qualifier : modifier = value 
#pragma modifier qualifier : modifier 
#pragma modifier qualifier : modifier = value 



where "qualifier” is the identifier of an IDL definition or is user defined. If the "qualifier" is an IDL definition introduced in the current interface, 
module, or global scope, then the modifier is attached to that definition. Otherwise, if the qualifier is user defined, the modifier is attached to 
the interface it occurs in. If a user-defined modifier is defined outside of an interface body (by using #pragma modifier), then it is ignored. 

For example, consider the following IDL file. (Notice that qualified modifiers can be defined with the "qualifier" and "modifier[=value]" in either 
order. Also observe that additional modifiers can be included by separating them with commas.) 

ftinclude <somobj.idl> 
ftinclude <somcls.idl> 




typedef long newlnt; 

#pragma somemittypes on 
#pragma modifier newlnt : nonportable; 
#pragma somemittypes off 
module M { 

typedef long long_t; 
module N { 

typedef short short_t; 
interface M_I : SOMClass { 
implementation { 

somlnit : override; 



interface I : SOMObject { 
void op ( ) ; 

#pragma modifier op : persistent; 



typedef char char_t; 
implementation { 

releaseorder : op; 
metaclass = M_I; 
callstyle = oidl; 
mymod : a, b; 
mymod : c, d; 
e : mymod; 

f : mymod; 

op : persistent; 




From the preceding IDL file, we associate modifiers with the following definitions: 

TypeDef "::newlnt" 1 modifier: nonportable 

InterfaceDef " : :M: :N: :M_I" 1 modifier: override = somlnit 

InterfaceDef "::M::N::I" 9 modifiers: metaclass = M_I, 

releaseorder = op 
callstyle = oidl 
mymod = a,b,c,d,e,f 
a = mymod 
b = mymod 
c = mymod 
d = mymod 
e = mymod 
f = mymod 

OperationDef " : :M: :N: : I : :op" 1 modifier: persistent 



Notice, how the modifiers for the user-defined qualifier "mymod": 



mymod 

mymod 

e 

f 



a, b; 
c, d; 
mymod; 
mymod; 



map onto: 



mymod 

a 

b 

c 

d 

e 

f 



mymod 

mymod 

mymod 

mymod 

mymod 

mymod 



This enables users to look up the modifiers with "mymod", either by looking for "mymod" or by using each individual value that uses 
"mymod". These user-defined modifiers are available for Emitter writers (see the Emitter Writer's Guide and Reference) and from the 
Interface Repository (see Chapter 7, "The Interface Repository Framework"). 




SOM Compiler unqualified modifiers 



Unqualified modifiers (described below) include the SOM Compiler-defined identifiers abstract, baseproxyclass, callstyle, classinit, 
directinitclasses, dllname, filestem, functionprefix, majorversion, metaclass, memorymanagement, minorversion, somallocte and 
somdeallocate. 



abstract 



baseproxyclass =class 



callstyle = oidl 



classinit = procedure 



Specifies that the class is intended for use as a parent for subclass derivations, 
but not for creating instances. 

Specifies the base proxy class to be used by DSOM when dynamically creating a 
proxy class for the current class. The base proxy class must be derived from the 
class SOMDClientProxy The SOMDClientProxy class will be used if the 
baseproxyclass modifier is unspecified. (See chapter 6, "distributed SOM," for a 
discussion on customizing proxy classes.) 

Specifies that the method stub procedures generated by SOM's C/C++ bindings 
will not include the CORBA-specified ( Environment *ev) and ( context *ctx ) 
parameters. 

Specifies a user-written procedure that will be executed to complete the 
initialization of a class object after it is created. The classinit modifier is needed if 
something should happen exactly once when a class is created. (That is, you 
want to define an action that will not be inherited when subclasses are created. 
One example of this is for staticdata variables.) When the classinit modifier is 
specified in the .idl file for a class, the implementation file generated by the SOM 
Compiler provides a template for the procedure, which includes a parameter that is 
a pointer to the class. The class implementor can then fill in the body of this 
procedure template. (For an example, see the examples following the staticdata 
modifier under "SOM Compiler qualified modifiers.") 



directinitclasses = 'ancestor t, ancestor2, ... 



Specifies the ancestor class(es) whose initializers (and destructors) will be directly 
invoked by this class's initialization (and destruction) routines. If this modifier is not 
explicitly specified, the default setting is the parents of the class. For further 
information, see "Initializing and Uninitializing Objects" in Chapter 5, 

"Implementing Classes in SOM." 

dllname = fi/ename Specifies the name of the library file that will contain the class's implementation. If 

fi/ename contains special characters (e.g., periods, backslashes), then fi/ename 
should be surrounded by double quotes ("”). The fi/ename specified can be either 
a full pathname, or an unqualified (or partially qualified) filename. In the latter 
cases, the LIBPATFI environment variable is used to locate the file. 

filestem = stem Specifies how the SOM Compiler will construct file names for the binding files it 

generates (<stem>.h, <stem>.c, etc.). The default stem is the file stem of the .idl 
file for the class. 

functionprefix = prefix Directs the SOM Compiler to construct method-procedure names by prefixing 

method names with "prefix”. For example, "functionprefix = xx;" within an 
implementation statement would result in a procedure name of xxf oo for 
method f oo. The default for this attribute is the empty string. If an interface is 
defined in a module, then the default function prefix is the fully scooped interface 
name. Tip-. Using a function prefix with the same name as the class makes it 
easier to remember method-procedure names when debugging. 

When an .idl file defines multiple interfaces not contained within a module, use of a 
function prefix for each interface is essential to avoid name collisions. 

For example, if one interface introduces a 

method and another interface in the same .idl file overrides it, then the 
implementation file for the classes will contain two method procedures of the same 
name (unless function prefixes are defined for one of the classes), resulting in a 
name collision at compile time. 

majorversion = number Specifies the major version number of the current class definition. The major 

version number of a class definition usually changes only when a significant 
enhancement or incompatible change is made to the class. The "number” must be 
a positive integer less than 2[32]-1 . If a non-zero major version number is 




specified, SOM will verify that any code that purports to implement the class has 
the same major version number. The default major version number is zero. 



memory management = corba 



metaclass = c/ass 



minorversion = number 



somallocate= procedure 



Specifies that all methods introduced by the class follow the CORBA specification 
for parameter memory management, except where a particular method has an 
explicit modifier indicating otherwise (either ”object_owns_result" or 
"object_owns_parameters"). See the section in Chapter 6 entitled "Memory 
Management” for a discussion of the CORBA memory-management requirements. 

Specifies the class's metaclass. The specified metaclass (or one automatically 
derived from it at run time) will be used to create the class object for the class. If a 
metaclass is specified, its .idl file (if separate) must be included in the include 
section of the class's .idl file. If no metaclass is specified, the metaclass will be 
defined automatically. 

Specifies the minor version number of the current class definition. The minor 
version number of a class definition changes whenever minor enhancements or 
fixes are made to a class. Class implementers usually maintain backward 
compatibility across changes in the minor version number. The ''number” must be 
a positive integer less than 2[32]-1 . If a non-zero minor version number is 
specified, SOM will verify that any code that purports to implement the class has 
the same or a higher minor version number. The default minor version number is 
zero. 

Specifies a user-written procedure that will be executed to allocate memory for 
class instances when the somAllocate class method is invoked. 



somdeallocat ^procedure 



Specifies a user-written procedure that will be executed to deallocate memory for 
class instances when the somDeallocate class method is invoked. 



The following example illustrates the specification of unqualified interface modifiers: 



implementation 

{ 

filestem = hello; 
f unctionpref ix = hel; 
majorversion = 1; 
minorversion = 2; 
classinit = hellolnit; 
metaclass = M_Hello; 



SOM Compiler qualified modifiers 



Qualified modifiers are categorized according to the IDL component (class, attribute, method, or type) to which each modifier applies. Listed 
below are the SOM Compiler-defined identifiers used as qualified modifiers, along with the IDL component to which it applies. Descriptions 
of all qualified modifiers are then given in alphabetical order. Recall that qualified modifiers are defined using the syntax qua/iffer. 
mod/f/er\= va/ue\. 

For classes: 

releaseorder 

For attributes: 

indirect, nodata, noget, noset 

For methods: 

caller_owns_parameters, caller_owns_result, const, init, method, migrate, namelookup, nocall, noenv, nonstatic, 
nooverride, noself, object_owns_parameters, object_owns_result, offset, override, procedure, reintroduce, and select 

For variables: 

staticdata 



For types: 



impctx 




caller_owns_parameters = ”pt,p2,.. 



caller_owns_result 

const 

impctx 

indirect 

init 

method or nonstatic or procedure 
migrate = ancestor 

namelookup 

nocall 

nodata 



■,pn" 



Specifies the names of the method's parameters whose ownership is retained by 
(in the case of ''in"parameters) or transferred to (for "inout" or "out" parameters) 
the caller. This modifier is only valid in the interface specification of the method's 
introducing class. This modifier only makes sense for parameters whose IDL type 
is a data item that can be freed (string, object, array, pointer, or TypeCode), or a 
data item containing memory that can be freed (for example, a sequence or any), 
or a struct or union. 

For parameters whose type is an object, ownership applies to the object reference 
rather than to the object (that is, the caller should invoke release on the 
parameter, rather than somFree). 

Specifies that ownership of the return result of the method is transferred to the 
caller, and that the caller is responsible for freeing the memory. This modifier is 
only valid in the interface specification of the method's introducing class. This 
modifier only makes sense when the method's return type is a data type that can 
be freed (string, object, array, pointer, or TypeCode), or a data item containing 
memory that can be freed (for example, a sequence or any). For methods that 
return an object, ownership applies to the object reference rather than to the object 
(that is, the caller should invoke release on the result, rather than somFree). 

Indicates that implementations of the related method should not modify their target 
argument. SOM provides no way to verify or guarantee that implementations do 
not modify the targets of such methods, and the information provided by this 
modifier is not currently of importance to any of the Toolkit emitters. Flowever, the 
information may prove useful in the future. For example, since modifiers are 
available in the Interface Repository, there may be future uses of this information 
by DSOM. 

Supports types that cannot be fully defined using IDL. For full information, see 
"Using the tk_foreign TypeCode” in Chapter 7, "The Interface Repository 
Framework." 

Directs the SOM Compiler to generate "get" and "set” methods for the attribute 
that take and return a pointer to the attribute's value, rather than the attribute value 
itself. For example, if an attribute x of type float is declared to be an indirect 
attribute, then the "_get_x" method will return a pointer to a float, and the input to 
the "_set_x” method must be a pointer to a float. (This modifier is provided for 
OIDL compatibility only.) 

Indicates that a method is an initializer method. For information concerning the use 
of this modifier, see "Initializing and Uninitializing Objects: in Chapter 5, 
"Implementing Classes in SOM" 



Indicates the category of method implementation. Refer to the topic "The four 
kinds of SOM methods" in Chapter 5, "Implementing Classes in SOM," for an 
explanation of the meanings of these different method modifiers. If none of these 
modifiers is specified, the default is method. Methods with the procedure modifier 
cannot be invoked remotely using DSOM. 

Indicates that a method originally introduced by this interface has been moved 
upward to a specified <ancestor> interface. When this is done, the method 
introduction must be removed from this interface (because the method is now 
inherited). Flowever, the original releaseorder entry for the method should be 
retained, and migrate should be used to assure that clients compiled based on the 
original interface will not require recompilation. The ancestor interface is specified 
using a C-scoped interface name. For example, "ModuleJnterfaceName", not 
"Module::lnterfaceName". See the later topic "Name usage in client programs" for 
an explanation of C-scoped names. 

See "offset or namelookup." 

Specifies that the related method should not be invoked on an instance of this 
class even though it is supported by the interface. 

Directs the SOM Compiler not to define an instance variable corresponding to the 
attribute. For example, a "time" attribute would not require an instance variable to 
maintain its value, because the value can be obtained from the operating system. 




noenv 

noget 

nonstatic 

nooverride 

noself 

noset 



object_owns_parameters 



object_owns_result 
offset or namelookup 



The "get" and "set" methods for "nodata" attributes must be defined by the class 
implementer; stub method procedures for them are automatically generated in the 
implementation template for the class by the SOM Compiler. 

Indicates that a direct-call procedure does not receive an environment as an 
argument. 

Directs the SOM Compiler not to automatically generate a "get" method 
procedure for the attribute in the .ih/.xih binding file for the class. Instead, the "get" 
method must be implemented by the class implementer. A stub method procedure 
for the "get" method is automatically generated in the implementation template for 
the class by the SOM Compiler, to be filled in by the implementer. 

See "method or nonstatic or procedure.” 

Indicates that the method should not be overridden by subclasses. The SOM 
Compiler will generate an error if this method is overridden. 

Indicates that a direct-call procedure does not receive a target object as an 
argument. 

Directs the SOM Compiler not to automatically generate a "set" method procedure 
for the attribute in the .ih/.xih binding file for the class. Instead, the "set" method 
must be implemented by the class implementer. A stub method procedure for the 
"set" method is automatically generated in the implementation template for the 
class by the SOM Compiler. 

Note: The "set" method procedure that the SOM Compiler generates by default for 
an attribute in the .h/.xh binding file (when the noset modifier is not used) does a 
shallow copy of the value that is passed to the attribute. For some attribute types, 
including strings and pointers, this may not be appropriate. For instance, the "set" 
method for an attribute of type string should perform a string copy, rather than a 
shallow copy, if the attribute's value may be needed after the client program has 
freed the memory occupied by the string. In such situations, the class implementer 
should specify the noset attribute modifier and implement the attribute's "set" 
method manually, rather than having SOM implement the "set" method 
automatically. 



"pi, p2, pn" 



Specifies the names of the method's parameters whose ownership is transferred 
to (in the case of "in" parameters) or is retained by (for "inout" or "out" parameters) 
the object. For "in” parameters, the object can free the parameter at any time 
after receiving it. (Flence, the caller should not reuse the parameter or pass it as 
any other object-owned parameter in the same method call.) For "inout" and "out" 
parameters, the object is responsible for freeing the parameter sometime before 
the object is destroyed. This modifier is only valid in the interface specification of 
the method's introducing class. This modifier only makes sense for parameters 
whose IDL type is a data item that can be freed (string, object, array, pointer, or 
TypeCode), or a data item containing memory that can be freed (for example, a 
sequence or any), or a struct or union. 

For parameters whose type is an object, ownership applies to the object reference 
rather than to the object (that is, the object will invoke release on the parameter, 
rather than somFree). For "in" and "out" parameters whose IDL-to-C/C++ 
mapping introduces a pointer, ownership applies only to the data item itself, and 
not to the introduced pointer. (For example, even if an "out string" IDL parameter 
(which becomes a "string *" C/C++ parameter) is designated as "object-owned," 
the object assumes ownership of the string, but not of the pointer to the string.) 

Specifies that the object retains ownership of the return result of the method, and 
that the caller must not free the memory. The object is responsible for freeing the 
memory sometime before the object is destroyed. This modifier is only valid in the 
interface specification of the method's introducing class. This modifier only makes 
sense when the method's return type is a data type that can be freed (string, 
object, array, pointer, or TypeCode), or a data item containing memory that can be 
freed (for example, a sequence or any). For methods that return an object, 
ownership applies to the object reference rather than to the object (that is, the 
object will be responsible for invoking release on the result, rather than somFree). 

Indicates whether the SOM Compiler should generate bindings for invoking the 
method using offset resolution or name lookup. Offset resolution requires that the 
class of the method's target object be known at compile time. When different 




override 



procedure 

reintroduce 



releaseorder: a, b, c, ... 



methods of the same name are defined by several classes, namelookup is a 
more appropriate technique for method resolution than is offset resolution. (See 
Chapter 3, the section entitled "Invoking Methods.") The default modifier is offset. 

Indicates that the method is one introduced by an ancestor class and that this 
class will re-implement the method. See also the related modifier, select. 

See "method or nonstatic or procedure." 

Indicates that this interface will "hide" a method introduced by some ancestor 
interface, and will replace it with another implementation. Methods introduced as 
direct-call procedures or nonstatic methods can be reintroduced. However, static 
methods (the default implementation category for SOM met hods) cannot be 
reintroduced. 

Specifies the order in which the SOM Compiler will place the class's methods in 
the data structures it builds to represent the class. Maintaining a consistent 
release order for a class allows the implementation of a class to change without 
requiring client programs to be recompiled. 

The release order should contain every method name introduced by the class 
(private and nonprivate), but should not include any inherited methods, even if 
they are overridden by the class. The "get" and "set" methods defined 
automatically for each new attribute (named "_get_<attributeName>" and 
"_set_<attributeName>”) should also be included in the release order list. The 
order of the names on the list is unimportant except that once a name is on the list 
and the class has client programs, it should not be reordered or removed, even if 
the method is no longer supported by the class, or the client programs will require 
recompilation. New methods should be added only to the end of the list. If a 
method named on the list is to be moved up in the class hierarchy, its name 
should remain on the current list, but it should also be added to the release order 
list for the class that will now introduce it. 



If not explicitly specified, the release order will be determined by the SOM 
Compiler, and a warning will be issued for each missing method. If new methods 
or attributes are subsequently added to the class, the default release order might 
change; programs using the class would then require recompilation. Thus, it is 
advisable to explicitly give a release order. 

select = parent Used in conjunction with the override modifier, this, indicates that an inherited 

static method will use the implementation inherited from the indicated <parent> 
class. The parent is specified using the C-scoped name. For example, 
"ModuleJnterfaceName", not "Module:: InterfaceName". See the later topic 
"Name usage in client programs" for an explanation of C-scoped names. 

staticdata Indicates that the declared variable is not stored within objects, but, instead, that 

the ClassData structure for the implementing class will contain a pointer to the 
staticdata variable. This is similar in concept to C++ static data members. The 
staticdata variable must also be included in the releaseorder. The class 
implementor has responsibility for allocating the staticdata variable and for 
loading the ClassData structure's pointer to the staticdata variable during class 
initialization. (The pointer is accessible as 

<c/assA/ame>C\a.ssDaXd..<i/ar/ab/e/Vame>.) The implementor's responsibility can 
be facilitated by writing a special class initialization function and indicating its 
name using the classinit unqualified modifier. (See also the examples that follow.) 

Note: Attributes can be declared as staticdata. This is an important 

implementation technique that allows classes to introduce attributes whose 
backing storage is not inherited by subclasses. 

The following example illustrates the specification of qualified modifiers: 

implementation 

{ 

releaseorder : opl, op3, op2, op5, op6, x, y, _set_z, _get_z; 

opl : persistent; 

somDef aultlnit : override, init; 

op2 : reintroduce, procedure; 

op3 : reintroduce, nonstatic; 

op4 : override, select = ModuleName_parentInterf aceName; 
op5 : migrate = ModuleName_ancestorInterf aceName; 
op6: procedure, noself, noenv; 
long x; 




x: staticdata; 

y: staticdata; // y and z are attributes 
_set_z : ob ject_owns_parameters = "name"; 
_get_z : object_owns_result; 
mymod : a, b; 

}; 



As shown above for attribute z, separate modifiers can be declared for an attribute's _set and _get methods, using method modifiers. This 
capability may be useful for DSOM applications. (See the DSOM sample program "animal” that is distributed with the SOMobjects Toolkit.) 

The next example for classes "X" and "Y" illustrates the use of a staticdata modifier, along with its corresponding classinit modifier and the 
template procedure generated for classinit by the SOM Compiler. 

/* IDL for staticdata and classinit example: */ 

((include <somobj.idl> 

interface X : SOMObject { 

attribute long staticAttribute; 
attribute long normalAttribute; 
implementation { 

staticAttribute: staticdata; 
classinit = Xinit; 
releaseorder : staticAttribute, 

_get_s t at icAt tribute, 

_set_s t at icAt tribute, 

_get_normal At tribute, 

_set_normalAttribute ; 




interface Y : X { }; 

/* Template procedure for classinit: */ 

#if ndef SOM_Module_classinit_Source 
#def ine SOM_Module_classinit_Source 
#endif 

#define X_Class_Source 

ftinclude "classinit . ih" 

static long holdStaticAttribute = 1234; 
void SOMLINK Xinit (SOMClass *cls) 

{ 

XClassData . staticAttribute = SholdStaticAttribute; 

} 

main ( ) 

{ 

X *x = XNew () ; 

Y *y = YNew ( ) ; 

somPrintf ( "initial staticAttribute = x(%d) = y(%d)\n", 

_get_staticAttribute (x, 0) , 
_get_staticAttribute (y, 0) ) ; 

_set_staticAttribute (x, 0,42) ; 

_set_staticAttribute (y, 0, 4321) ; 

somPrintf ("changed staticAttribute = x(%d) = y(%d)\n", 

_get_staticAttribute (x, 0) , 
_get_staticAttribute (y, 0) ) ; 

} 



/* Program output: 

initial staticAttribute = x(1234) = y(1234) 
changed staticAttribute = x(4321) = y (4321) 
after setting normalAttribute, x(10) != y ( 2 0 ) 




Passthru statements 



A passthru statement (used within the body of an implementation statement, described above) allows a class implementer to specify 
blocks of code (for C/C++ programmers, usually only #include directives) that the SOM compiler will pass into the header files it generates. 

Passthru statements are included in SOM IDL primarily for backward compatibility with the SOM OIDL language, and their use by C and 
C++ programmers should be limited to #include directives. C and C++ programmers should use IDL type and constant declarations rather 
than passthru statements when possible. (Users of other languages, however, may require passthru statements for type and constant 
declarations.) 

The contents of the passthru lines are ignored by the SOM compiler and can contain anything that needs to placed near the beginning of a 
header file for a class. Even comments contained in passthru lines are processed without modification. The syntax for specifying passthru 
lines is one of the following forms: 

passthru language _suff/x = /itera/+ ; 

passthru language _suli/x_beiore = literal + ; 

passthru language _ suffix ja f t e r = literal + ; 

where "language" specifies the programming language and "suffix" indicates which header files will be affected. The SOM Compiler 
supports suffixes h, ih, xh, and xih. For both C and C++, "language" is specified as C. 

Each "literal" is a string literal (enclosed in double quotes) to be placed verbatim into the specified header file. [Double quotes within the 

passthru literal should be preceded by a backslash. No other characters escaped with a backslash will be interpreted, and formatting 
characters (newlines, tab characters, etc.) are passed through without processing.] The last literal for a passthru statement must not end in a 
backslash (put a space or other character between a final backslash and the closing double quote). 

When either of the first two forms is used, passthru lines are placed before the #include statements in the header file. When the third form 

is used, passthru lines are placed just after the #include statements in the header file. 

For example, the following passthru statement 

implementation 

{ 

passthru C_h = "#include <foo.h>"; 

}; 



results in the directive #include <f oo . h> being placed at the beginning of the .h C binding file that the SOM Compiler generates. 

For any given target file (as indicated by ianguage_suffix ), only one passthru statement may be defined within each implementation 
section. You may, however, define multiple #include statements in a single passthru. For legibility, each #include should begin on a new 
line, optionally with a blank line to precede and follow the #include list. For an example, see "Introducing non-IDL data types or classes" later 
in this section. 



Declaring instance variables and staticdata variables 



Declarators are used within the body of an implementation statement (described above) to specify the instance variables that are 
introduced by a class, and the staticdata variables pointed to by the class's ClassData structure. These variables are declared using ANSI C 
syntax for variable declarations, restricted to valid SOM IDL types (see "Type and constant declarations," above). For example, the following 
implementation statement declares two instance variables, x and y, and a staticdata variable, z, for class "Hello," : 

implementation 

{ 

short x; 
long y; 
double z; 
z: staticdata; 

} ; 



Instance variables are normally intended to be accessed only by the class's methods and not by client programs or subclasses' methods. 
For data to be accessed by client programs or subclass methods, attributes should be used instead of instance variables. (Note, however, 
that declaring an attribute has the effect of also declaring an instance variable of the same name, unless the "nodata" attribute modifier is 
specified.) 




Staticdata variables, by contrast, are publicly available and are associated specifically with their introducing class. They are, however, very 
different in concept from class variables. Class variables are really instance variables introduced by a metaclass, and are therefore present 
in any class that is an instance of the introducing metaclass (or of any metaclass derived from this metaclass). As a result, class variables 
present in any given class will also be present in any class derived from this class (that is, class variables are inherited). In contrast, 
staticdata variables are introduced by a class (not a metaclass) and are (only) accessed from the class's ClassData structure - they are not 
inherited. 



Introducing non-IDL data types or classes 



On occasion, you may want a new .idl file to reference some element that the SOM Compiler would not recognize, such as a user-defined 
class or an instance variable or attribute with a user-defined data type. You can reference such elements if they already exist in ,h or .xh files 
that the SOM Compiler can #include with your new .idl file, as follows: 

• To introduce a non-IDL class, insert an interface statement that is a forward reference to the existing user-defined class. It must 
precede the interface statement for the new class in the .idl file. 

• To declare an instance variable or attribute that is not a valid IDL type, declare a dummy typedef preceding the interface 
declaration. 

• In each case above, in the implementation section use a passthru statement to pass an #include statement into the 
language-specific binding file(s) of the new .idl file (a) for the existing user-defined class or (b) for the real typedef. 

In the following example, the generic SOM type somToken is used in the .idl file for the user's types "myRealType" and "myStructType". 

The passthru statement then causes an appropriate #include statement to be emitted into the C/C++ binding file, so that the file defining 
types "myRealType" and "myStructType" will be included when the binding files process. In addition, an interface declaration for 
"myOtherClass" is defined as a forward reference, so that an instance of that class can be used within the definition of "myCurrentClass". 
The passthru statement also //includes the binding file for "myOtherClass": 

typedef somToken myRealType; 
typedef somToken myStructType; 

interface myOtherClass; 

interface myCurrentClass : SOMObject { 

implementation { 

myRealType mylnstVar; 
attribute myStructType stl; 
passthru C_h = 

"#include <myTypes.h>" 

"#include <myOtherClass . h>" 




Note: See also the section "Using the tkjoreign TypeCode" in Chapter 7, "The Interface Repository Framework." 



Comments within a SOM IDL file 



SOM IDL supports both C and C++ comment styles. The characters "//" start a line comment, which finishes at the end of the current line. 
The characters "/*" start a block comment that finishes with the "7". Block comments do not nest. The two comment styles can be used 
interchangeably. 

Comments in a SOM IDL specification must be strictly associated with particular syntactic elements, so that the SOM Compiler can put them 
at the appropriate place in the header and implementation files it generates. Therefore, comments may appear only in these locations (in 
general, following the syntactic unit being commented): 

• At the beginning of the IDL specification 




After a semicolon 



• Before or after the opening brace of a module, interface statement, implementation statement, structure definition, or union 
definition 

• After a comma that separates parameter declarations or enumeration members 

• After the last parameter in a prototype (before the closing parenthesis) 

• After the last enumeration name in an enumeration definition (before the closing brace) 

• After the colon following a case label of a union definition 

• After the closing brace of an interface statement 

Numerous examples of the use of comments can be found in the Tutorial of Chapter 2. 

Because comments appearing in a SOM IDL specification are transferred to the files that the SOM Compiler generates, and because these 
files are often used as input to a programming language compiler, it is best within the body of comments to avoid using characters that are 
not generally allowed in comments of most programming languages. For example, the C language does not allow "7" to occur within a 
comment, so its use is to be avoided, even when using C++ style comments in the .idl file. 

SOM IDL also supports throw-away comments. They may appear anywhere in an IDL specification, because they are ignored by the SOM 
Compiler and are not transferred to any file it generates. Throw-away comments start with the string "//#" and end at the end of the line. 
Throw-away comments can be used to ''comment out" portions of an IDL specification. 

To disable comment processing (that is, to prevent the SOM Compiler from transferring comments from the IDL specification to the binding 
files it generates), use the -c option of the sc or some command when running the SOM Compiler (See Section 4.3, "The SOM Compiler"). 
When comment processing is disabled, comment placement is not restricted and comments can appear anywhere in the IDL specification. 



Designating 'private' methods and attributes 



To designate methods or attributes within an IDL specification as "private," the declaration of the method or attribute must be surrounded 

with the preprocessor commands #ifdef PRIVATE (with two leading underscores and two following underscores) and #endif. For 

example, to declare a method "foo" as a private method, the following declaration would appear within the interface statement: 



ftifdef PRIVATE. 

void foo ( ) ; 
#endif 



Any number of methods and attributes can be designated as private, either within a single #ifdef or in separate ones. [Kernighan-Ritchie 
reference for the C preprocessor: pages 88-92.] 

When compiling an .idl file, the SOM Compiler normally recognizes only public (nonprivate) methods and attributes, as that is generally all 
that is needed. To generate header files for client programs that do need to access private methods and attributes, or for use when 
implementing a class library containing private methods, the -p option should be included when running the SOM Compiler. The resulting 
header files will then include bindings for private, as well as public, methods and attributes. Both the implementation bindings (.ih or .xih file) 
and the usage bindings to be #included in the implementation (.h or .xh file) should be generated under the -p option. The -p option is 
described in the topic "Running the SOM Compiler" later in this chapter. 

The SOMobjects Toolkit also provides a pdl (Public Definition Language) emitter that can be used with the SOM Compiler to generate a 
copy of an .idl file which has the portions designated as private removed. The next main section of this chapter describes how to invoke the 
SOM Compiler and the various emitters. 



Module declarations to define multiple interfaces in a .idl file 



A single .idl file can define multiple interfaces. This allows, for example, a class and its metaclass to be defined in the same file. When a 
file defines two (or more) interfaces that reference one another, forward declarations can be used to declare the name of an interface before 
it is defined. This is done as follows: 



interface c/ass-name ; 




The actual definition of the interface for "class-name" must appear later in the same .idl file. 

If multiple interfaces are defined in the same .idl file, and the classes are not a class-metaclass pair, they can be grouped into modules, by 
using the following syntax: 

module modu/e-name { definitions }; 

where each "definition" is a type declaration, constant declaration, exception declaration, interface statement, or nested module 
statement. Modules are used to scope identifiers (see below). 

Alternatively, multiple interfaces can be defined in a single .idl file without using a module to group the interfaces. Whether or not a module is 
used for grouping multiple interfaces, the languages bindings produced from the .idl file will include support for all of the defined interfaces. 

Note: When multiple interfaces are defined in a single .idl file and a module statement is not used for grouping these interfaces, it is 

necessary to use the functionprefix modifier to assure that different names exist for functions that provide different implementations 
for a method. In general, it is a good idea to always use the functionprefix modifier, but in this case it is essential. 



Scooping and name resolution 



A idl file forms a naming scope (or scope). Modules, interface statements, structures, unions, methods, and exceptions form nested 
scopes. An identifier can only be defined once in a particular scope. Identifiers can be redefined in nested scopes. 

Names can be used in an unqualified form within a scope, and the name will be resolved by successively searching the enclosing scopes. 
Once an unqualified name is defined in an enclosing scope, that name cannot be redefined. 

Fully qualified names are of the form: 

scoped-name :: identifier 

For example, method name "meth" defined within interface "Test” of module "Ml" would have the fully qualified name: 

Ml : : Test : : meth 



A qualified name is resolved by first resolving the "scoped-name" to a particular scope S, then locating the definition of "identifier" within that 
scope. Enclosing scopes of S are not searched. 

Qualified names of the form: 

.■.identifier 

These names are resolved by locating the definition of "identifier" within the smallest enclosing module. 

Every name defined in an IDL specification is given a global name, constructed as follows: 

• Before the SOM Compiler scans an .idl file, the name of the current root and the name of the current scope are empty. As each 
module is encountered, the string and the module name are appended to the name of the current root. At the end of the 
module, they are removed. 

• As each interface, struct, union, or exception definition is encountered, the string and the associated name are appended to 
the name of the current scope. At the end of the definition, they are removed. While parameters of a method declaration are 
processed, a new unnamed scope is entered so that parameter names can duplicate other identifiers. 

• The global name of an IDL definition is then the concatenation of the current root, the current scope, a and the local name 
for the definition. 

The names of types, constants, and exceptions defined by the parents of a class are accessible in the child class. References to these 
names must be unambiguous. Ambiguities can be resolved by using a scoped name (prefacing the name with the name of the class that 
defines it and the characters as in "parent-class::identifier). Scope names can also be used to refer to a constant, type, or exception 
name defined by a parent class but redefined by the child class. 



Name usage in client programs 




Within a C or C++ program, the global name for a type, constant, or exception corresponding to an IDL scoped name is derived by 
converting the string to an underscore and removing the leading underscore. Such names are referred to as C-scoped names. This 
means that types, constants, and exceptions defined within the interface statement for a class can be referenced in a C/C++ program by 
prepending the class name to the name of the type, constant, or exception. For example, consider the types defined in the following IDL 
specification: 

typedef sequence<long, 10> mySeq; 
interface myClass : SOMObject 
{ 

enum color {red, white, bluet; 
typedef string<100> longString; 

} 



These types could be accessed within a C or C++ program with the following global names: 

mySeq, 

myClass_color , 
myClass_red, 
myClass_white, 
myClass_blue, and 
myClass_longString . 



Type, constant, and exception names defined within modules similarly have the module name prepended. When using SOM's C/C++ 
bindings, the short form of type, constant, and exception names (such as, color, longString) can also be used where 
unambiguous, except that enumeration names must be referred to using the long form (for example, myClass_red and not simply 

red). 

Because replacing with an underscore to create global names can lead to ambiguity if an IDL identifier contains underscores, it is best to 
avoid the use of underscores when defining IDL identifiers. 



Extensions to CORBA IDL permitted by SOM IDL 



The following topics describe several SOM-unique extensions of the standard CORBA syntax that are permitted by SOM IDL for 
convenience. These constructs can be used in an .idl file without generating a SOM Compiler error. 

If you want to verify that an IDL file contains only standard CORBA specifications, the SOM Compiler option -mcorba turns off each of these 
extensions and produces compiler errors wherever non-CORBA specifications are used. (The SOM Compiler command and options are 
described in the topic "Running the SOM Compiler” later in this chapter.) 



Pointer types 



In addition to the base CORBA types, SOM IDL permits the use of pointer types ('*'). As well as increasing the range of base types available 
to the SOM IDL programmer, using pointer types also permits the construction of more complex data types, including self-referential and 
mutually recursive structures and unions. 

If self-referential structures and unions are required, then, instead of using the CORBA approach for IDL sequences, such as the following: 

struct X { 

sequence <X> self; 

}; 



it is possible to use the more typical C/C++ approach. For example: 



struct X { 




X *self; 



}; 

SOM IDL does not permit an explicit in sequence declarations. If a sequence is required for a pointer type, then it is necessary to typedef 
the pointer type before use. For example: 

sequence dong *> long_star_seq; // error, 

typedef long * long_star; 

sequence <long_star> long_star_seq; // OK. 



Unsigned types 



SOM IDL permits the syntax "unsigned <type>'\ where <type> is a previously declared type mapping onto "short” or "long”. (Note that 
CORBA permits only "unsigned short" and "unsigned long".) 



Implementation section 



SOM IDL permits an implementation section in an IDL interface specification to allow the addition of instance variables, method overrides, 
metaclass information, passthru information, and "pragma-like" information, called modifiers, for the emitters. See the topic "Implementation 
statements" earlier in this chapter. 



Comment processing 



The SOM IDL Compiler by default does not remove comments in the input source; instead, it attaches them to the nearest preceding IDL 
statement. This facility is useful, since it allows comments to be emitted in header files, C template files, documentation files, and so forth. 
Flowever, if this capability is desired, this does mean that comments cannot be placed with quite as much freedom as with an ordinary IDL 
compiler. To turn off comment processing so that you can compile .idl files containing comments placed anywhere, you can use the compiler 
option -c or use "throw-away" comments throughout the .idl file (that is, comments preceded by //#); as a result, no comments will be 
included in the output files. 



Generated header files 



CORBA expects one header file, <f//e>. h, to be generated from <fi/e>\&\. Flowever, SOM IDL permits use of a class modifier, filestem, that 
changes this default output file name. (See "Running the SOM Compiler" later in this chapter.) 



The SOM Compiler 



The SOM Compiler translates the IDL definition of a SOM class into a set of "binding files" appropriate for the language that will implement 
the class's methods and the language(s) that will use the class. These bindings make it more convenient for programmers to implement and 
use SOM classes. The SOM Compiler currently produces binding files for the C and C++ languages. 

Important Note: C and C++ bindings can not both be generated during the same execution of the SOM compiler. 




Generating binding files 



The SOM Compiler operates in two phases: 

• A precompile phase , in which a precompiler analyzes an OIDL or IDL class definition, and 

• An emission phase , in which one or more emitter programs produce binding files. 

Each binding file is generated by a separate emitter program. Setting the SMEMIT environment variable determines which emitters will be 
used, as described below. Note: In the discussion below, the < filesvstem > is determined by default from the name of the source .idl file with 
the ".idl" extension removed. Otherwise, a "filestem" modifier can be defined in the .idl file to specify another file name (see "Modifier 
statements" above). 

Note: If changes to definitions in the .idl file later become necessary, the SOM Compiler should be rerun to update the current 
implementation template file, provided that the c or xc emitter is specified (either with the -s option or the SMEMIT environment variable, as 
described below). For more information on generating updates, see "Running incremental updates of the implementation template file" later 
in this chapter. 

The emitters for the C language produce the following binding files: 

<fi/estem>.c (produced by the c emitter) 

This is a template for a C source program that implements a class's methods. This 
will become the primary source file for the class. (The other binding files can be 
generated from the .idl file as needed.) This template implementation file contains 
"stub" procedures for each method introduced or overridden by the class. (The 
stub procedures are empty of code except for required initialization and debugging 
statements.) 

After the class implementer has supplied the code for the method procedures, 
running the c emitter again will update the implementation file to reflect changes 
made to the class definition (in the .idl file). These updates include adding new 
stub procedures, adding comments, and changing method prototypes to reflect 
changes made to the method definitions in the IDL specification. Existing code 
within method procedures is not disturbed, however. 

The .c file contains an #include directive for the .ih file, described below. 

The contents of the C source template is controlled by the Emitter Framework file 
<SOMBASE>/include/ctm.efw. This file can be customized to change the template 
produced. For detailed information on changing the template file see the Emitter 
Framework Guide and Reference . 

<fi/estem>.\\ (produced by the h emitter) 

This is the header file to be included bv C client programs (programs that use the 
class). It contains the C usage bindings for the class, including macros for 
accessing the class's methods and a macro for creating new instances of the 
class. This header file includes the header files for the class's parent classes and 
its metaclass, as well as the header file that defines SOM's generic C bindings, 
som.h. 

<fi/estem>M\ (produced by the ih emitter) 

This is the header file to be included in the implementation file (the file that 
implements the class's methods-the .c file). It contains the implementation 
bindings for the class, including: 

• a struct defining the class's instance variables, 

• macros for accessing instance variables, 

• macros for invoking parent methods the class overrides, 

• the <c/assiVame> GetData macro used by the method procedures in 
the <fiiestem>.c file (see "Stub procedures for methods" in Section 5.4 
of Chapter 5.) 

• a <ciassAiame>Ne\ivC\ass procedure for constructing the class object 
at run time, and 

• any IDL types and constants defined in the IDL interface. 




The emitters for the C++ language produce the following binding files: 



<fiiestem>.Q, (for AIX) or <f/iestem >.cpp (for OS/2) (produced by the xc emitter) 

This is a template for a C++ source program that implements a class's methods. 
This will become the primary source file for the class. (The other binding files can 
be generated from the .idl file as needed.) This template implementation file 
contains "stub" procedures for each method introduced or overridden by the class. 
(The stub procedures are empty of code except for required initialization and 
debugging statements.) 

After the class implementer has supplied the code for the method procedures, 
running the xc emitter again will update this file to reflect changes made to the 
class definition (in the .idl file). These updates include adding new stub 
procedures, adding comments, and changing method prototypes to reflect 
changes made to the method definitions in the IDL specification. Existing code 
within method procedures is not disturbed, however. 

The C++ implementation file contains an #include directive for the .xih file, 
described below. 

The contents of the C++ source template is controlled by the Emitter Framework 
file <SOMBASE>/include/ctm.efw. This file can be customized to change the 
template produced. For detailed information on changing the template file see the 
Emitter Framework Guide and Reference . 

<fi/estem>.tCn (produced by the xh emitter) 

This is the header file to be included bv C++ client programs that use the class. It 
contains the usage bindings for the class, including a C++ definition of the class, 
macros for accessing the class's methods, and the new operator for creating new 
instances of the class. This header file includes the header files for the class's 
parent classes and its metaclass, as well as the header file that defines SOM’s 
generic C++ bindings, som.xh. 

<fi/estem>.nu\\ (produced by the xih emitter) 

This is the header file to be included in the implementation file (the file that 
implements the class's methods). It contains the implementation bindings for the 
class, including: 

• a struct defining the class's instance variables, 

• macros for accessing instance variables, 

• macros for invoking parent methods the class overrides, 

• the <c/ass/Vame> GetData macro (see section 5.4), 

• a <ciassAiame>Ne\hiC\ass procedure for constructing the class object 
at run time, and 

• any IDL types and constants defined in the IDL interface. 



Other files the SOM Compiler generates: 

(produced by the hh emitter) 

This file is a DirectToSOM C++ header file that describes a SOMobjects class in a 
way appropriate to DTS C++. When running this emitter, you must include the 
noqualitytypes command-line modifier for the -m optionof the SOM Compiler 
command sc or some. 

(produced by the pdl emitter) This file is the same as the .idl file from which it is 
produced except that all items within the .idl file that are marked as "private" have 
been removed, (an item is marked as private by surrounding it with 
"#ifdef_PRIVATE_" and "#endif" directives. Thus, the pdl (Public Definition 
Lnguage) emitter can be used to generate a "public" version of the .idl file. 

<f/iestem>.def (for OS/2) (produced by the def emitter) 

This file is used bv the linker to package a class as a library . To combine several 
classes into a single library, you must merge the exports statements from each of 
their .def files into a single .def file for the entire library. When packaging multiple 
classes in a single library, you must also write a simple C procedure named 
SOMInitModule and add it to the export list. This procedure should call the routine 
<c/assiVame> NewClass for each class packaged in the library. The 



<fi/estem>.\\h 



<f/iestem >pd\ 




SOMInitModule procedure is called by the SOM Class Manager when the library 
is dynamically loaded. 

(produced by the exp emitter) 

This file is used bv the linker to package a class as a library . To combine several 
classes into a single library, you must merge the exports statements from each of 
their .exp files into a single .exp file for the entire library. When packaging multiple 
classes in a single library, you must also write a simple C procedure named 
SOMInitModule and add it to the export list. This procedure should call the routine 
<c/ass/Vame>NewC\ass for each class packaged in the library The 
SOMInitModule procedure is called by the SOM Class Manager when the library 
is dynamically loaded. 

(produced by the ir emitter) 

See Chapter 7 for a discussion on the Interface Repository. 

Note: The C/C++ bindings generated by the SOM Compiler have the following limitation: If two classes named "ClassName" and 
"ClassNameC" are defined, the bindings for these two classes will clash. That is, if a client program uses the C/C++ bindings (includes the 
.h/.xh header file) for both classes, a name conflict will occur. Thus, class implementers should keep this limitation in mind when naming 
their classes. 

SOM users can extend the SOM Compiler to generate additional files by writing their own emitters. To assist users in extending the SOM 
Compiler, SOM provides an Emitter Framework a collection of classes and methods useful for writing object-oriented emitters that the SOM 
Compiler can invoke. For more information, see the Emitter Framework Guide and Reference . 

Note re: porting SOM classes: The header files (binding files) that the SOM Compiler generates will only work on the platform (operating 
system) on which they were generated. Thus, when porting SOM classes from the platform where they were developed to another platform, 
the header files must be regenerated from the .idl file by the SOM Compiler on that target platform. 



<fi/estem>.exp (for AIX) 



The Interface Repository 



Environment variables affecting the SOM Compiler 



To execute the SOM Compiler on one or more files that contain IDL specifications for one or more classes, use the sc. or some as follows: 
sc [-options] fi/es (on AIX or OS/2) 
some options] fi/es (on Windows) 

where "files" specifies one or more .idl files. 

Available "-options" for the command are detailed in the next topic. The operation of the SOM Compiler (whether it produces C binding files 
or C++ binding files, for example) is also controlled by a set of environment variables that can be set before the sc command is issued. The 
applicable environment variables are as follows: 

SMEMIT Determines which output files the SOM Compiler produces. Its value consists of a list of items 

separated by semicolons for OS/2, or by semicolons or colons for AIX. Each item designates 
an emitter to execute. For example, the statement: 

SET SMEMIT=c; h; ih (for OS/2, for C binding 

files) 

export SMEMIT=" c; h; ih" (for AIX) 

directs the SOM Compiler to produce the C binding files "hello. c". "hello. h", and"hello.ih" from 
the "hello. idl" input specification. By comparison, 

SET SMEMIT=xc; xh; xih (for OS/2) 

export SMEMIT="xc; xh; xih" (for AIX) 

directs the SOM Compiler to produce C++ binding files "hello. C" (for AIX) or "hello. epp" (for 
OS/2), "hello. xh", and "hello. xih" from the "hello. idl" input specification. 

By default, all output files are placed in the same directory as the input file. If the SMEMIT 
environment variable is not set, then a default value of "h;ih" is assumed. 

Windows note: The SMEMIT environmental variable can be set by using the SET command 
before the some command is issued. For example: 




SET SMEMIT="c; h; ih 



(for Windows) 



If you are running the SOM Compiler from a DOS box under Windows, make sure to define 
SMEMIT before Windows is started. 

SMINCLUDE Specifies where the SOM Compiler should look for .idl files #included by the .idl file being 

compiled. Its value should be one or more directory names separated by a semicolon when 
using OS/2, or separated by a semicolon or colon when using AIX. Directory names can be 
specified with absolute or relative pathnames. For example: 

SET SMINCLUDE= . ; . . \MYSCDIR; C: \TOOLKT2 0 \C\ INCLUDE ; 

(for OS/2 or Windows) 



export SMINCLUDE=. : myscdir : /u/som/include 

(for AIX) 

The default value of the SMINCLUDE environment variable is the "include" subdirectory of the 
directory into which SOM has been installed. 

SMTMP Specifies the directory that the SOM Compiler should use to hold intermediate output files. 

This directory should not coincide with the directory of the input or output files. For AIX, the 
default setting of SMTMP is /tmp; for OS/2, the default setting of SMTMP is the root directory 
of the current drive. 

OS/2 or Windows example: 

SET SMTMP=. . \MYSCDIR\GARBAGE 



tells the SOM Compiler to place the temporary files in the GARBAGE directory. 
Or, on OS/2 only: 

SET SMTMP=%TMP% 



tells the SOM Compiler to use the same directory for temporary files as given by the setting of 
the TMP environment variable (the defult location for temporary system files). (On Windows, 
you cannot set one variable to another.) 

AIX example: 

export SMTMP=$TMP 

export SMTMP= .. /myscdir /garbage 



SMKNOWNEXTS Specifies additional emitters to which the SOM Compiler should add a header. For example, if 

you were to write a new emitter for Pascal, called "emitpas", then by default the SOM 
Compiler would not add any header comments to it. However, by setting 
SMKNOWNEXTS=pas, as shown: 

set SMKNOWNEXTS=pas (for OS/2 or Windows) 

export SMKNOWNEXTS=pas (for AIX) 

the SOM Compiler will add a header to files generated with the "emitpas" emitter. The 
"header" added is a SOM Compiler-generated message plus any comments, such as 
copyright statements, that appear at the head of your .idl input file. For details on writing your 
own emitter, see the Emitter Framework Guide and Reference . 

SOMIR Specifies the name (or list of names) of the Interface Repository file. The ir emitter, if run, 

creates the Interface Repository, or checks it for consistency if it already exists. If the -u option 
is specified when invoking the SOM Compiler, the ir emitter also updates an existing Interface 
Repository. 

SMADDSTAR When defined, causes all interface references to have a added to them for the C bindings. 

The command-line options -maddstar and -mnoaddstar supercede and override the 
SMADDSTAR setting, however. 

Note: Environment variables that affect the SOM Compiler can be set for any -m options of the SOM Compiler command. See the -m option 
in the following topic, "Running the SOM Compiler." Also, the -E option in the following topic can be used to set an environment 




variable. 



Running the SOM Compiler 



The syntax of the command for running the SOM Compiler takes the forms: 
sc [- options \ fi/es 
somc[ -options\ fi/es 

The "files" specified in the sc or some command denote one or more files containing the IDL class definitions to be compiled. If no 
extension is specified, .idl is assumed. By default, the <filestem> of the ,idl file determines the filestem of each emitted file. Otherwise, a 
"filestem" modifier can be defined in the .idl file to specify another name (see "Modifier statements" discussed earlier). 

Selected "-options "can be specified individually, as a string of option characters, or as a combination of both. Any option that takes an 
argument either must be specified individually or must appear as the final option in a string of option characters. Available options and their 
purposes are as follows: 



-C/7 



-D name\=def\ 



-E variab/e=va/ue 



-I dir 



-S n 



-U name 

-V 

-c 



-d directory 



-h or -? 



-i fi/ename 



-m name\=va/ue\ 



Sets the maximum allowable size for a simple comment in the .idl file (default: 32767). This is only needed for 
very large single comments. 

Defines name as in a #define directive. The default def is 1 . This option is the same as the -D option for the C 

compiler. Note: This option can be used to define PRIVATE so that the SOM Compiler will also compile any 

methods and attributes that have been defined as private using the directive #ifdef PRIVATE ; however, the 

-p option does the same thing more easily. When a class contains private methods or attributes, both the 
implementation bindings and the usage bindings to be #included in the implementation should be generated 
using either the -p or -D_PRIVATE_ option. 

Sets an environment variable. (See the previous topic for a discussion of the available environment variables: 
SMADDSTAR, SMEMIT, SMINCLUDE, SMTMP, SMKNOWNEXTS, and SOMIR.) 

When looking for #included files, looks first in dir, then in the standard directories (same as the C compiler -I 
option). 

Sets the total allowable amount of unique string space used in the IDL specification for names and passthru lines 
(default: 32767). This is only needed for very large .idl files. 

Removes any initial definition (via a #define preprocessor directive) of symbol name. 

Displays version information about the SOM Compiler. 

Turns off comment processing. This allows comments to appear anywhere within an IDL specification (rather 
than in restricted places), and it causes comments not to be transferred to the output files that the SOM Compiler 
produces. 

Specifies a directory where all output files should be placed. If the -d option is not used, all output files are 
placed in the same directory as the input file. 

Produces a listing of this option list. (This option is typically used in an sc or some command that does not 
include a .idl file name) 

Specifies the name of the class definition file. Use this option to override the built-in assumption that the input file 
will have a .idl extension. Any Zi/ename supplied with the -i option is used exactly as it is specified. 

Adds a global modifier. (See the following Note on the -m options, which explains how to convert any "-m name" 
modifier to an environment variable.) 

Note: All command-line -m modifier options can be specified in the environment by changing them to 

UPPERCASE and prepending " SM" to them. For example, if you want to always set the options "-mnotc" 
and "-maddstar”, set corresponding environment variables as follows: 

On OS/2: 

set SMNOTC=l 
set SMADDSTAR=1 




On AIX: 



export SMNOTC=l 
export SMADDSTAR=1 



The currently supported global modifiers for the -m name\=va/ue\ option are as follows: 

addprefixes Adds 'functionprefixes' to the method procedure prototypes during 

an incremental update of the implementation template file. This 
option applies only when rerunning the c or xc emitter on an IDL 
file that previously did not specify a functionprefix. A class 
implementor who later decides to use prefixes should add a line in 
the 'implementation' section of the .idl file containing the 
specification: 

functionprefix = prefix 

(as described earlier in the topic "Modifier statements") and then 
rerun the c or xc emitter using the -maddprefixes option. The 
method procedure prototypes in the implementation file will then 
be updated so that each method name includes the assigned 
prefix. (This option does not support changes to existing prefix 
names, nor does it apply for OIDL files.) 

addstar This option causes all interface references to have a added to 

them for the C bindings. See the earlier section entitled "Object 
types” for further details. 

comment= comment string where comment string can be either of the designations: "/*" or 

"II". This option indicates that comments marked in the designated 
manner in the .idl file are to be completely ignored by the SOM 
Compiler and will not be included in the output files. Note: 
Comments on lines beginning with "//#” are always ignored by the 
SOM Compiler. 

corba This option directs the SOM Compiler to compile the input 

definition according to strict CORBA-defined IDL syntax. This 
means, for example, that comments may appear anywhere and 
that pointers are not allowed. When the -mcorba option is used, 

parts of a .idl file surrounded by #ifdef SOMIDL and #endif 

directives are ignored. This option can be used to determine 
whether all nonstandard constructs (those specific to SOM IDL) 

are properly protected by #ifdef SOMIDL and #endif 

directives. 

esc This option forces the OIDL compiler to be run. This is required 

only if you want to compile an OIDL file that does not have an 
extension of .esc or .sc. 

emitappend This option causes emitted files to be appended at the end of 

existing files of the same name. 

noaccessors This option turns off the automatic creation of OperationDef 

entries in the Interface Repository for attribute accessors (that is, 
for an attribute's _set and _get methods). 

noaddstar This option ensures that interface references will not have a 

added to them for the C bindings. This is the default setting: it is 
the opposite of the -m compiler option addstar. 

noint This option directs the SOM Compiler not to warn about the 

portability problems of using int's in the source. 

nolock This option causes the Interface Repository Emitter emitir (see 

Chapter 7, "Interface Repository Framework") to leave the IR 
unlocked when updates are made to it. This can improve 
performance on networked file systems. By not locking the IR, 
however, there is the risk of multiple processes attempting to write 
to the same IR, with unpredictable results. This option should only 
be used when you know that only one process is updating an IR at 




once. 
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s string 



nopp This option directs the SOM Compiler not to run the SOM 

preprocessor on the .idl input file. 

noqualifytypes This option prevents the use od C-scoped names in emitter 

output, and is used in conjunction with the .hh emitter. 

note This option directs the SOM Compiler not to create TypeCode 

information when emitting IDL files that contain some undeclared 
types. This option is only used when compiling converted .esc files 
(that is, OIDL files originally) that have not had typing information 
added. 

This option directs the SOM Compiler not to generate short forms 
for type names in the .h and .xh public header files. This can be 
useful to save disk space. 

This option tells the SOM Compiler that, in declarations containing 
a linkage specifier, the "*" will appear before the linkage specifier. 
This is required when using any C++ compiler (Watcom is a 
known example) that cannot handle declarations in the default 
format where the follows the linkage specifier. A default 
example is the declaration: 

typedef void (SOMLINK * somTD_SOMOb ject_somFree) 
(SOMObject *somSelf ) ; 



Under the -mpbl option of the SOM Compiler command, the same 
example would be declared as: 

typedef void (* SOMLINK somTD_SOMOb ject_somFree) 
(SOMObject *somSelf ) ; 



pp= preprocessor This option directs the SOM Compiler to use the specified 

preprocessor as the SOM preprocessor, rather than the default 
"somepp". Any standard C/C++ preprocessor can be used as a 
preprocessor for IDL specifications. 

tcconsts This option directs the SOM Compiler to generate TypeCode 

constants in the h and .xh public header files. Please refer to the 
Interface Repository (described in Chapter 7) for more details. 

Causes the "private” sections of the IDL file to be included in the compilation (that is, sections preceded by #ifdef 

PRIVATE that contain private methods and attributes). Note: If -p is used, it must be applied for both the 

implementation bindings (.ih or .xih file) and the usage bindings (.h or .xh file) to be #included in the 
implementation. 

Checks that all names specified in the release order statement are valid method names (default: FALSE). 

Substitutes string in place of the contents of the SMEMIT environment variable for the duration of the current sc 
command. This determines which emitters will be run and, hence, which output files will be produced. (If a list of 
values is given, on OS/2 on/y the list must be enclosed in double quotes.) 

The -s option is a convenient way to override the SMEMIT environment variable. In OS/2 for example, the 
command: 

> SC -s"h; c" EXAMPLE 



nouseshort 



pbl 



is equivalent to the following sequence of commands: 

> SET OLDSMEMIT=%SMEMIT% 

> SET SMEMIT=H; C 

> SC EXAMPLE 

> SET SMEMIT=%OLDSMEMIT% 



Similarly, in AIX the command: 



> sc -sh";"c example 




is equivalent to the following sequence of commands: 



> export OLDSMEMIT=$SMEMIT 

> export SMEMIT=h";"c 

> sc example 

> export SMEMIT=$OLDSMEMIT 

-u Updates the Interface Repository (default: no update). With this option, the Interface Repository will be updated 

even if the ir emitter is not explicitly requested in the SMEMIT environment variable or the -s option. 

-v Uses verbose mode to display informational messages (default: FALSE). This option is primarily intended for 

debugging purposes and for writers of emitters. 

-w Suppresses warning messages (default: FALSE). 

The following sample commands illustrate various options for the sc command or similarly with some): 

sc -sc hello, idl Generates file "hello. c". 

sc -hV Generates a help message and displays the version of the SOM Compiler 

currently available. 

sc -vsh";"ih hello. idl Generates "hello. h" and "hello. ih" with informational messages, 

sc -sxc -doutdir hello, idl Generates "hello.xc” in directory "outdir". 



The 'pdr Facility 



As discussed earlier in this chapter, the SOM Compiler provides a pdl (Public Definition Language) emitter. This emitter generates a file that 
is the same as the .idl file from which it is produced, except that it removes all items within the .idl file that are marked as "private." An item is 

marked as private by surrounding it with "#ifdef PRIVATE " and "#endif" directives. Thus, the pdl emitter can be used to generate a 

"public" version of a .idl file. (Generally, client programs will need only the "public" methods and attributes.) 

The SOMobjects Toolkit also provides a separate program, pdl, which performs the same function as the pdl emitter, but can be invoked 
independently of the SOM Compiler. In addition, the pdl program can remove any kind of items in the .idl file that are preceded by a 
user-specified "#ifdef" directive and followed by an "#endif” directive: The pdl program is invoked as follows: 

pdl [ -c | d | f | h | s |/] files 

where "files" specifies one or more .idl files whose specified "#ifdef" sections are to be removed. Filenames must be completely specified 

(with the .idl extension). If no ”#ifdef" directive is specified (by including a -/<string> option), then the "#ifdef PRIVATE "sections will be 

removed by default. 

The pdl command supports the following options. (Selected options can be specified individually, as a string of option characters, or as a 
combination of both. Any option that takes an argument either must be specified individually or must appear as the final option in a string of 
option characters.) 



-c cmd 



-d dir 



-h 

-f 



-s smemit 



Specifies that, for each .idl file, the pdl program is to run the specified system command. This command may 
contain a single occurrence of the string "%s", which will be replaced with the source file name before the 
command is executed. For example the option -c”sc -sh %s" has the same effect as issuing the sc command 
with the -sh option. 

Specifies a directory in which the output files are to be placed. (The output files are given the same name as the 
input files.) If no directory is specified, the output files are named <f/ieStem >. pdl (where f/ieStem is the file stem 
of the input file) and are placed in the current working directory. 

Requests this description of the pdl command syntax and options. 

Specifies that output files are to replace existing files with the same name, even if the existing files are read-only. 
By default, files are replaced only if they have write access. 

Specifies the SMEMIT variable with which the pdl program is to 



invoke the SOM Compiler. 




-/ <string> Specifies the "#ifdef" pattern for which the pdl program will strip out .idl statements. The default is "#ifdef 

_PRIVATE 

For example, to install public versions of the .idl files in the directory "pubinclude", type: 

pdl -d pubinclude * . idl 



Implementing Classes in SOM 

This chapter begins with a more in-depth discussion of SOM concepts and the SOM run-time environment than was appropriate in Tutorial 
for Implementing SOM Classes. Subsequent sections then provide information about completing an implementation template file, updating 
the template file, compiling and linking, packaging classes in libraries, and other useful topics for class implementors. During this process, 
you can refer to Chapter 4, "SOM IDL and the SOM Compiler," if you want to read the reference information or see the full syntax related to 
topics discussed in this chapter. The current chapter ends with topics describing how to customize SOMobjects execution in various ways. 



The SOM Run-Time Environment 



The SOMobjects Developer Toolkit provides 



• The SOM Compiler, used when creating SOM class libraries, and 

• The SOM run-time library, for using SOM classes at execution time. 

The SOM run-time library provides a set of functions used primarily for creating objects and invoking methods on them. The data structures 
and objects that are created, maintained, and used by the functions in the SOM run-time library constitute the SOM run-time 
environment. 

A distinguishing characteristic of the SOM run-time environment is that SOM c/asses are represented bv run-time objects -, these objects 
are called class objects . By contrast, other object-oriented languages such as C++ treat classes strictly as compile-time structures that have 
no properties at run time. In SOM, however, each class has a corresponding run-time object. This has three advantages: First, application 
programs can access information about a class at run time, including its relationships with other classes, the methods it supports, the size of 
its instances, and so on. Second, because much of the information about a class is established at run time rather than at compile time, 
application programs needn't be recompiled when this information changes. Finally, because class objects can be instances of user-defined 
classes in SOM, users can adapt the techniques for subclassing and inheritance in order to build object-oriented solutions to problems that 
are otherwise not easily addressed within an OOP context. 



Run-time environment initialization 



When the SOM run-time environment is initialized, four primitive SOM objects are automatically created. Three of these are class objects 
(SOMObject, SOMCIass, and SOMCIassMgr), and one is an instance of SOMCIassMgr, called the SOMCIassMgrObject. Once loaded, 
application programs can invoke methods on these class objects to perform tasks such as creating other objects, printing the contents of an 
object, freeing objects, and the like. These four primitive objects are discussed below. 

In addition to creating the four primitive SOM objects, initialization of the SOM run-time environment also involves initializing global variables 
to hold data structures that maintain the state of the environment. Other functions in the SOM run-time library rely on these global variables. 

For application programs written in C or C++ that use the language-specific bindings provided by SOM, the SOM run-time environment is 
automatically initialized the first time any object is created . Programmers using other languages must initialize the run-time environment 
explicitly by calling the somEnvironmentNew function (provided by the SOM run-time library) before using any other SOM functions or 
methods. 



SOMObject class object 



SOMObiect is the root class for all SOM c/asses . It defines the essential behavior common to all SOM objects . All user-defined SOM 
classes are derived, directly or indirectly, from this class. That is, every SOM class is a subclass of SOMObject or of some other class 
derived from SOMObject. SOMObject has no instance variables, thus objects that inherit from SOMObject incur no size increase. They do 
inherit a suite of methods that provide the behavior required of all SOM objects. 



SOMCIass class object 



Because SOM classes are run-time objects, and since all run-time objects are instances of some class, it follows that a SOM class object 
must also be an instance of some class. The class of a class is called a metac/ass . Flence, the instances of an ordinary class are individuals 
(nonclasses), while the instances of a metaclass are class objects. 

In the same way that the class of an object defines the "instance methods” that the object can perform, the metaclass of a class defines the 
"class methods" that the class itself can perform. C/ass methods (sometimes called factory methods or constructors ) are performed bv 
class objects . Class methods perform tasks such as creating new instances of a class, maintaining a count of the number of instances of the 
class, and other operations of a "supervisory" nature. Also, class methods facilitate inheritance of instance methods from parent classes. For 
information on the distinction between parent classes and metaclasses, see the section "Parent Class vs. metaclass," later in this chapter. 

SOMCIass is the root class for all SOM metac/asses . That is, all SOM metaclasses must be subclasses of SOMCIass or of some 
metaclass derived from SOMCIass. SOMCIass defines the essential behavior common to all SOM class objects . In particular, SOMCIass 





provides: 



• Six class methods for creating new class instances: somNew, somNewNolnit, somRenew, somRenewNolnit, 
somRenewNoZero and somRenewNolnitNoZero. 

• A number of class methods that dynamically obtain or update information about a class and its methods at run time, including: 

somlnitMICIass, for implementing multiple inheritance from parent classes, 

somOverrideSMethod, for overriding inherited methods, and 

somAddStaticMethod and somAddDynamicMethod, for including new methods. 

SOMCIass is a subclass (or child) of SOMObject. Hence, SOM c/ass objects can also perform the same set of basic instance methods 
common to all SOM objects. This is what allows SOM classes to be real objects in the SOM run-time environment. SOMCIass also has the 
unique distinction of being its own metaclass (that is, SOMCIass defines its own class methods). 

A user-defined class can designate as its metaclass either SOMCIass or another user-written metaclass descended from SOMCIass. If a 
metaclass is not explicitly specified, SOM determines one automatically. 



SOMCIassMgr class object and SOMCIassMgrObject 



The third primitive SOM class is SOMCIassMgr. A single instance of the SOMCIassMgr class is created automatically during SOM 
initialization. This instance is referred to as the SOMCIassMgrObject, because it is pointed to by the g/obai var/ab/e SOMCIassMgrObject. 
The object SOMCIassMgrObject has the responsibility to 

• Maintain a registry (a run-time directory) of all SOM classes that exist within the current process, and to 

• Assist in the dynamic loading and unloading of class libraries. 

For C/C++ application programs using the SOM C/C++ language bindings, the SOMCIassMgrObject automatically loads the appropriate 
library file and constructs a run-time object for the class the first time an instance of a class is created. For programmers using other 
languages, SOMCIassMgr provides a method, somFindClass, for directing the SOMCIassMgrObject to load the library file for a class and 
create its class object. 

Again, the primitive classes supplied with SOM are SOMObject, SOMCIass, and SOMCIassMgr. During SOM initialization, the latter class 
generates an instance called SOMCIassMgrObject. The SOMObject class is the parent class of SOMCIass and SOMCIassMgr. The 
SOMCIass class is the metaclass of itself, of SOMObject, and of SOMCIassMgr, which are all class objects at run time. SOMCIassMgr is 
the class of SOMCIassMgrObject. 



Parent class vs. metaclass 



There is a distinct difference between the notions of "parent" (or base) class and "metaclass." Both notions are related to the fact that a 
class defines the methods and variables of its instances, which are therefore called instance methods and instance variab/es. 

A parent of a given class is a class from which the given class is derived by subc/assing. (Thus, the given class is called a chi/d or a 
subc/ass of the parent.) A parent class is a class from which instance methods and instance variables are inherited . For example, the 
parent of class "Dog" might be class "Animal". Hence, the instance methods and variables introduced by "Animal" (such as methods for 
breathing and eating, or a variable for storing an animal's weight) would also apply to instances of "Dog", because "Dog" inherits these from 
"Animal", its parent class. As a result, any given dog instance would be able to breath and eat, and would have a weight. 

A metac/ass is a class whose instances are class objects, and whose instance methods and instance variables (as described above) are 
therefore the methods and variables of class objects. For this reason, a metac/ass is said to define c/ass methods -the methods that a class 
object performs. For example, the metaclass of "Animal" might be "AnimalMCIass", which defines the methods that can be invoked on class 
"Animal" (such as, to create Animal instances-objects that are not classes, like an individual pig or cat or elephant or dog). 

Note: It is important to distinguish the methods of a class object (that is, the methods that can be invoked on the class object, which are 
defined by its metaclass) from the methods that the class defines for its instances. 

To summarize: the parent of a class provides inherited methods that the class's instances can perform : the metac/ass of a class provides 
class methods that the c/ass itse/f can perform . These distinctions are further summarized below: The distinctions between parent class and 
metaclass are summarized in A class has both parent classes and a metaclass. 




A class has both parent classes and a metaclass 




Any class "C" has both a metac/ass and one or more parent class(es). 

• The parent class(es) of "C" provide the inherited instance methods that individual instances (objects "0{i}”) of class "C" can 
perform. Instance methods that an instance ”0{i}" performs might include (a) initializing itself, (b) performing computations using 
its instance variables, (c) printing its instance variables, or (d) returning its size. New instance methods are defined by "C" itself, 
in addition to those inherited from C's parent classes. 

• The metac/ass "M”defines the c/ass methods that class "C" can perform. For example, class methods defined by metaclass "M" 
include those that allow "C" to (a) inherit its parents' instance methods and instance variables, (b) tell its own name, (c) create 
new instances, and (d) tell how many instance methods it supports. These methods are inherited from SOMCIass. Additional 





methods supported by "M” might allow "C" to count how many instances it creates. 

• Each class "C" has one or more parent classes and exactly one metaclass. (The single exception is SOMObject, which has no 
parent class.) Parent class(es) must be explicitly identified in the IDL declaration of a class. (SOMObject is given as a parent if 
no subsequently-derived class applies.) If a metaclass is not explicitly listed, the SOM run time will determine an applicable 
metaclass. 

• An instance of a metaclass is always another c/ass object. For example, class ”C" is an instance of metaclass "M”. SOMCIass is 
the SOM-provided metaclass from which all subsequent metaclasses are derived. 

A metaclass has its own inheritance hierarchy (through its parent classes) that is independent of its instances' inheritance hierarchies. For 
example, suppose a series of classes is defined (or derived), stemming from SOMObject. The child class (or subclass) at the end of this line 
("C[2j") inherits instance methods from all of its ancestor classes (here, SOMObject and "C[1 ]"). An instance created by ”C2" can perform 
any of these instance methods. In an analogous manner, a line of metaclasses can be defined, stemming from SOMCIass. Just as a new 
class is derived from an existing class (such as SOMObject), a new metaclass is derived from an existing metaclass (such as SOMCIass). 

Parent classes and metaclasses each have their own 
independent inheritance hierrarchies 




SOM-derived metaclasses 





As previously discussed, a class object can perform any of the class methods that its metaclass defines. New metaclasses are typically 
created to modify existing class methods or introduce new class method(s). Chapter 8, "Metaclass Framework," discusses metaclass 
programming. 

Three factors are essential for effective use of metaclasses in SOM: 

• First, every class in SOM is an object that is implemented by a metaclass. 

• Second, programmers can define and name new metaclasses, and can use these metaclasses when defining new SOM 
classes. 

• Finally, and most importantly, metaclasses cannot interfere with the fundamental guarantee required of every OOP system: 
specifically, any code that executes without method-resolution error on instances of a given class will also execute without 
method-resolution errors on instances of any subclass of this class. 

Surprisingly, SOM is currently the only OOP system that can make this final guarantee while also allowing programmers to explicitly define 
and use named metaclasses. This is possible because SOM automatically determines an appropriate metaclass that supports this 
guarantee, automatically deriving new metaclasses by subclassing at run time when this is necessary. As an example, suppose class "A" is 
an instance of metaclass "AMeta". 

Assume that "AMeta" supports a method "bar" and that "A" supports a method "foo" that uses the expression "_bar(_somGetClass(somSelf 
) )." That is, method "foo" invokes "bar" on the class of the object on which "foo" is invoked. For example, when method "foo" is invoked on 
an instance of class "A" (say, object "0{1 }"), this in turn invokes "bar" on class "A" itself. 

Now consider what happens if class "A" were subclassed by "B," a class that has the explicit metaclass "BMeta" declared in its SOM IDL 
source file (and assuming "BMeta" is not derived from "AMeta"). Also assume that object ”0{2}" is an instance of class "B." 

Recall that "AMeta" supports method "bar" and that class "A" supports method "foo" (which incorporates "bar" in its definition). Given the 
hierarchy described above, an invocation of "foo" on "O {2}" would fail, because metaclass "BMeta" does not support the "bar" method. 

Example of Metaclass Incompatibility 




There is only one way that "BMeta" can support this specific method-by inheriting it from "AMeta" ("BMeta" could introduce another method 
named "bar", but this would be a d/fferent method from the one introduced by "AMeta"). Therefore, in this example, because "BMeta" is not 
a subclass of "AMeta", "BMeta" cannot be allowed to be the metaclass of "B". That is, "BMeta" is not compatible with the requirements 
placed on "B" by the fundamental principle of OOP referred to above. This situation is referred to as metac/ass incompat/bi/ity . 

SOM does not allow hierarchies with metaclass incompatibilities. Instead, SOM automatically builds derived metac/asses when this is 
necessary. For example, SOM would create a "DerivedMeta" metaclass that has both "AMeta" and "BMeta" as parents. This ensures that 
the invocation of method "foo” on instances of class "B" will not fail, and also ensures that the desired class methods provided by "BMeta" 
will be available on class "B". 





Example of a Derived Metaclass 




There are three important aspects of SOM's approach to derived metaclasses: 

• First, the creation of SOM-derived metaclasses is integrated with programmer-specified metaclasses. If a programmer-specified 
metaclass already supports all the class methods and variables needed by a new class, then the programmer-specified 
metaclass will be used as is. 

• Second, if SOM must derive a different metaclass than the one explicitly indicated by the programmer (in order to support all the 
necessary class methods and variables), then the SOM-derived metaclass inherits from the explicitly indicated metaclass first. 
As a result, the method procedures defined by the specified metaclass take precedence over other possibilities (see the 
following section on inheritance and the discussion of resolution of ambiguity in the case of multiple inheritance). 

• Finally, the class methods defined by the derived metaclass invoke the appropriate initialization methods of its parents to ensure 
that the class variables of its instances are correctly initialized. 

As further explanation for the automatic derivation of metaclasses, consider the following multiple-inheritance example. Class "C" (derived 
from classes "A" and "B") does not have an explicit metaclass declaration in its SOM IDL, yet its parents "A" and "B" do. As a result, class 
"C" requires a derived metaclass. (If you still have trouble following the reasoning behind derived metaclasses, ask yourself the following 
question: What class should "C" be an instance of? After a bit of reflection, you will conclude that, if SOM did not build the derived 
metaclass, you would have to do so yourself.) 

Multiple Inheritance requires Derived Metaclasses 






In summary, SOM allows and encourages the definition and explicit use of named metaclasses. With named metaclasses, programmers can 
not only affect the behavior of class instances by choosing the parents of classes, but they can also affect the behavior of the classes 
themselves by choosing their metaclasses. Because the behavior of classes in SOM includes the implementation of inheritance itself, 
metaclasses in SOM provide an extremely flexible and powerful capability allowing classes to package solutions to problems that are 
otherwise very difficult to address within an OOP context. 

At the same time, SOM is unique in that it relieves programmers of the responsibility for avoiding metaclass incompatibility when defining a 
new class. At first glance, this might seem to be merely a useful (though very important) convenience. But, in fact, it is absolutely essential, 
because SOM is predicated on binary compatibility with respect to changes in class implementations. 

A programmer might, at one point in time, know the metaclasses of all ancestor classes of a new subclass, and, as a result, be able to 
explicitly derive an appropriate metaclass for the new class. Nevertheless, SOM must guarantee that this new class will still execute and 
perform correctly when any of its ancestor class's implementations are changed (which could even include specifying different metaclasses). 
Derived metaclasses allow SOM to make this guarantee. A SOM programmer need never worry about the problem of metaclass 
incompatibility; SOM does this for the programmer. Instead, explicit metaclasses can simply be used to "add in" whatever behavior is 
desired for a new class. SOM automatically handles anything else that is needed. Chapter 10 provides useful examples of such 
metaclasses. A SOM programmer should find numerous applications for the techniques that are illustrated there. 



Inheritance 



One of the defining aspects of an object model is its characterization of inheritance. This section describes SOM's model for inheritance. 

A class in SOM defines an implementation for objects that support a specific interface: 

• The interface defines the methods supported by objects of the class, and is specified using SOM IDL. 

• The imp/ementat/on defines what instance variables implement an object's state and what procedures implement its methods. 

New classes are derived (by subclassing) from previously existing classes through inheritance, specialization, and addition. Subclasses 
inherit interface from their parent classes: any method available on instances of a class is also available on instances of any class derived 
from it (either directly or indirectly). Subclasses also inherit implementation (the procedures that implement the methods) from their parent 
classes un/ess the methods are overridden (redefined or specialized). In addition, a subclass may introduce new instance methods and 
instance variables that will be inherited by other classes derived from it. 

SOM also supports mu/tip/e inheritance . That is, a class may be derived from (and may inherit interface and implementation from) multiple 
parent classes. Note: Multiple inheritance is available only to SOM classes whose interfaces are specified in IDL, and not to SOM classes 
whose interfaces are specified in SOM’s earlier interface definition language, OIDL. See Appendix B for information on how to automatically 
convert existing OIDL files to IDL. 




It is possible under multiple inheritance to encounter potential conflicts or ambiguities with respect to inheritance. All multiple inheritance 
models must face these issues, and resolve the ambiguities in some way. For example, when multiple inheritance is allowed, it is possible 
that a class will inherit the same method or instance variable from different parents (because each of these parents has some common 
ancestor that introduces the method or instance variable). In this situation, a SOM subclass inherits only one implementation of the method 
or instance variable. (The implementation of an instance variable within an object is just the location where it is stored. The implementation 
of a method is a procedure pointer, stored within a method table.) The following illustration addresses the question of which method 
implementation would be inherited. 

Consider this situation: Class "W" defines a method "foo", implemented by procedure “procl ". Class "W" has two subclasses, "X" and "Y". 
Subclass "Y" overrides the implementation of "foo" with procedure "proc2". Subclass "X" does not override "foo". In addition, classes "X" 
and "Y" share a common subclass, "Z". That is, the IDL interface statement for class "Z" lists its parents as "X" and "Y" in that order. (These 
relationships form a diamond shape, with class "W" at the top.) 

The question is thus: which implementation of method "foo" does class "Z" inherit-procedure "procl" defined by class "W", or procedure 
"proc2" defined by class "Y"? The procedure for performing inheritance that is defined by SOMCIass resolves this ambiguity by using the /eft 
path precedence rule: when the same method is inherited from multiple ancestors, the procedure used to support the method is the one 
used bv the leftmost ancestor from which the method is inherited . (The ordering of parent classes is determined by the order in which the 
class implementor lists the parents in the IDL specification for the class.) 

Class "Z" inherits the implementation of method "foo" defined by class "W" (procedure "procl"), rather than the implementation defined by 
class "Y" (procedure "proc2"), because "X" is the leftmost ancestor of "Z" from which the method "foo" is inherited. This rule may be 
interpreted as giving priority to classes whose instance interfaces are mentioned first in IDL interface definitions. 

If a class implementor decides that the default inherited implementation is not appropriate (for example, procedure "proc2" is desired), then 
SOM IDL allows the class designer to select the parent whose implementation is desired. For more information concerning this approach, 
see the Select modifier, which is documented in the topic "Modifier statements” in Chapter 4, "SOM IDL and the SOM Compiler." 

Note: Alternatively, an explicit metaclass for "Z" could be introduced to change the way methods are inherited. Flowever, this would be a 
fairly serious step to take-it would also affect the semantics of inheritance for all of Z's descendant classes. 



Another conflict that may arise with the use of multiple inheritance is when two ancestors of a class define different methods (in general, with 
different signatures) of the same name. For example, suppose Class "X" defines a method "bar" with type 77, and class "Y" defines a 
method "bar” with type T2. Class "Z" is derived from both "X" and "Y", and "Z" does not override method "bar". 

This example illustrates a method name that is ”overloaded"-that is, used to name two entirely different methods (note that overloading is 
completely unrelated to overriding). This is not necessarily a difficult problem to handle. Indeed, the run-time SOM API allows the 
construction of a class that supports the two different "bar" methods. (They are implemented using two different method-table entries, each 
of which is associated with its introducing class.) 

Flowever. the interface to instances of such classes can not be defined using IDL . IDL specifically forbids the definition of interfaces in which 
method names are overloaded. Furthermore, within SOM itself, the use of such classes can lead to anomalous behavior unless care is 
taken to avoid the use of name-lookup method resolution (discussed in the following section), since, in this case, a method name alone does 
not identify a unique method. For this reason, (statically declared) multiple-inheritance classes in SOM are currently restricted to those 
whose instance interfaces can be defined using IDL. Thus, the above example cannot be constructed with the aid of the SOM Compiler. 



Method Resolution 



Method resolution is the step of determining which procedure to execute in response to a method invocation. For example, consider this 
scenario: 



• Class "Dog" introduces a method "bark", and 

• A subclass of "Dog", called "BigDog", overrides "bark", and 

• A client program creates an instance of either "Dog" or "BigDog" (depending on some run-time criteria) and invokes method 
"bark" on that instance. 

Method resolution is the process of determining, at run time, which method procedure to execute in response to the method invocation 
(either the method procedure for "bark" defined by "Dog", or the method procedure for "bark" defined by "BigDog"). This determination 
depends on whether the receiver of the method (the object on which it is invoked) is an instance of "Dog" or "BigDog" (or perhaps depending 
on some other criteria). 

SOM allows class implementors and client programs considerable flexibility in deciding how SOM performs method resolution. In particular, 
SOM supports three mechanisms for method resolution, described in order of increased flexibility and increased computational cost: offset 
resolution, name-lookup resolution, and dispatch-function resolution. 




Offset resolution 



When using SOM's C and C++ language bindings, offset resolution is the default way of resolving methods, because it is the fastest. For 
those familiar with C++, it is roughly equivalent to the C++ "virtual function" concept. 

Although offset resolution is the fastest technique for method resolution, it is also the most constrained. Specifically, using offset resolution 
requires these constraints: 

• The name of the method to be invoked must be known at compile time, 

• The name of the class that introduces the method must be known at compile time (although not necessarily by the programmer), 
and 

• The method to be invoked must be part of the introducing class's static (IDL) interface definition. 

To perform offset method resolution, SOM first obtains a method token from a global data structure associated with the class that 
introduced the method. This data structure is called the C/assData structure . It includes a method token for each method the class 
introduces. The method token is then used as an “index" into the receiver's method tab/e, to access the appropriate method procedure. 
Because it is known at compile time which class introduces the method and where in that class's ClassData structure the method's token is 
stored, offset resolution is quite efficient. The cost of offset method resolution is currently about twice the cost of calling a C function using a 
pointer loaded with the function address. 

An object's method table is a table of pointers to the procedures that implement the methods that the object supports. This table is 
constructed by the object's class and is shared among the class instances. The method table built by class (for its instances) is referred to 
as the class's instance method tab/e . This is useful terminology, since, in SOM, a class is itself an object with a method table (created by its 
metaclass) used to support method calls on the class. 

Usually, offset method resolution is sufficient; however, in some cases, the more flexible name-lookup resolution is required. 



Name-lookup resolution 



Name-lookup resolution is similar to the method resolution techniques employed by Objective-C and Smalltalk. It is currently about five times 
slower than offset resolution. It is more flexible, however. In particular, name-lookup resolution, unlike offset resolution, can be used when: 

• The name of the method to be invoked isn't known until run time, or 

• The method is added to the class interface at run time, or 

• The name of the class introducing the method isn't known until run time. 

For example, a client program may use two classes that define two different methods of the same name, and it might not be known until run 
time which of the two methods should be invoked (because, for example, it will not be known until run time which class's instance the 
method will be applied to). 

Name-lookup resolution is always performed by a class, so it requires a method call. (Offset resolution, by contrast, requires no method 
calls.) To perform name-lookup method resolution, the class of the intended receiver object obtains a method procedure pointer for the 
desired method that is appropriate for its instances. In general, this will require a name-based search through various data structures 
maintained by ancestor classes. 

Offset and name-lookup resolution achieve the same net effect (that is, they select the same method procedure); they just achieve it 
differently (via different mechanisms for locating the method's method token). Offset resolution is faster, because it does not require 
searching for the method token, but name-lookup resolution is more flexible. 

When defining (in SOM IDL) the interface to a class of objects, the class implementor can decide, for each method, whether the SOM 
Compiler will generate usage bindings that support name-lookup resolution for invoking the method. Regardless of whether this is done, 
however, application programs using the class can have SOM use either technique, on a per-method-call basis. Chapter 3, "Using SOM 
Classes in Client Programs," describes how client programs invoke methods. 



Dispatch-function resolution 




Dispatch-function resolution is the slowest, but most flexible, of the three method-resolution techniques. Dispatch functions permit method 
resolution to be based on arbitrary rules associated with the class of which the receiving object is an instance. Thus, a class implementor 
has complete freedom in determining how methods invoked on its instances are resolved. 

With both offset and name-lookup resolution, the net effect is the same-the method procedure that is ultimately selected is the one 
supported by the class of which the receiver is an instance. For example, if the receiver is an instance of class "Dog", then Dog's method 
procedure will be selected; but if the receiver is an instance of class "BigDog", then BigDog's method procedure will be selected. 

By contrast, dispatch-function resolution allows a class of instances to be defined such that the method procedure is selected using some 
other criteria. For example, the method procedure could be selected on the basis of the arguments to the method call, rather than on the 
receiver. For more information on dispatch-function resolution, see the description and examples for the somDispatch and 
somOverrideMTab methods in the SOMobjects Deve/oper Too/k/t: Programmers Reference Manua/ . 



Customizing Method Resolution 



Customizing method resolution requires the use of metaclasses that override SOMCIass methods. This is not recommended without use of 
the Cooperative Metaclass that guarantees correct operation of SOMobjects in conjunction with such metaclasses. SOMobjects users who 
require this functionality should request access to the experimental Cooperative Metaclass used to implement the SOMobjects Metaclass 
Framework. Metaclasses implemented using the Cooperative Metaclass may have to be reprogrammed in the future when SOMobjects 
introduces an oficially supported Cooperative Metaclass. 



The four kinds of SOM methods 



SOM supports four different kinds of methods: static methods, nonstatic methods, dynamic methods, and direct-call procedures. The 
following paragraphs explain these four method categories and the kinds of method resolution available for each. 



Static methods 



These are similar in concept to C++ virtual functions. Static methods are normally invoked using offset resolution via a method table, as 
described above, but all three kinds of method resolution are applicable to static methods. Each different static method available on an 
object is given a different slot in the object's method table. When SOMobjects Toolkit language bindings are used to implement a class, the 
SOM IDL method modifier can be specified to indicate that a given method is static; however, this modifier is rarely used since it is the 
default for SOM methods. 

Static methods introduced by a class can be overridden (redefined) by any descendant classes of the class. When SOMobjects language 
bindings are used to implement a class, the SOM IDL override modifier is specified to indicate that a class overrides a given inherited 
method. When a static method is resolved using offset resolution, it is not important which interface is accessing the method - the actual 
class of the object determines the method procedure that is selected. 

Note: All SOM IDL modifiers are described in the topic "Modifier statements" in Chapter 4, "SOM IDL and the SOM Compiler." 



Nonstatic methods 



These methods are similar in concept to C++ nonstatic member functions (that is, C++ functions that are not virtual member functions and 
are not static member functions). Nonstatic methods are normally invoked using offset resolution, but all three kinds of method resolution are 
applicable to nonstatic methods. When the SOMobjects language bindings are used to implement a class, the SOM IDL nonstatic modifier 
is used to indicate that a given method is nonstatic. 



Like static methods, nonstatic methods are given individual positions in method tables. Flowever, nonstatic methods cannot be overridden. 
Instead, descendants of a class that introduces a nonstatic method can use the SOM IDL reintroduce modifier to "hide” the original 




nonstatic method with another (nonstatic or static) method of the same name. When a nonstatic method is resolved, selection of the specific 
method procedure is determined bv the interface that is used to access the method. 



Dynamic methods 



These methods are not declared when specifying an object interface using IDL. Instead, they are registered with a class object at run time 
using the method somAddDynamicMethod. Because there is no way for SOM to know about dynamic methods before run time, offset 
resolution is not available for dynamic methods. Only name-lookup or dispatch-function resolution can be used to invoke dynamic methods. 
Dynamic methods cannot be overridden. 



Direct-call procedures 



These are similar in concept to C++ static member functions. Direct-call procedures are not given positions in SOM method tables, but are 
accessed directly from a class's ClassData structure. Strictly speaking, none of the previous method-resolution approaches apply for 
invoking a direct-call procedure, although SOMobjects language bindings provide the same invocation syntax for direct-call procedures as 
for static or nonstatic methods. Direct-call procedures cannot be overridden, but they can be reintroduced. When SOMobjects language 
bindings are used to implement a class, the SOM IDL procedure modifier is used to indicate that a given method is a direct-call procedure. 
Note: Methods having the procedure modifier cannot be invoked remotely using DSOM. 



Implementing SOM Classes 



The interface to a class of objects contains the information that a client must know to use an object - namely, the signatures of its methods 
and the names of its attributes. The interface is described in a formal language independent of the programming language used to 
implement the object's methods. In SOM, the formal language used to define object interfaces is the Interface Definition Language 
(described in Chapter 4, "SOM IDL and the SOM Compiler"). 

The imp/ementat/on of a class of objects (that is, the procedures that implement the methods and the instance variables that store an 
object's state) is written in the implementor's preferred programming language. This language can be object-oriented (for instance, C++) or 
procedural (for instance, C). 

A completely implemented class definition, then, consists of two main files: 

• An IDL specification of the interface to instances of the class - the interface definition file (or .idl file) and 

• Method procedures written in the implementor's language of choice - the implementation file. 

The SOM Compiler provides the link between those two files: To assist users in implementing classes, the SOM Compiler produces a 
template implementation file - a type-correct guide for how the implementation of a class should look. Then, the class implementor modifies 
this template file to fully implement the class's methods. That process is the subject of the remainder of this chapter. 



TheSOM Compiler can also update the implementation file to reflect changes subsequently made to a class's interface definition file (the .idl 
file). These incremental updates include adding new stub procedures, adding comments, and changing method prototypes to reflect 
changes made to the method definitions in the IDL specification. These updates to the implementation file, however, do not disturb existing 
code in the method procedures. These updates are discussed further in "Running incremental updates of the implementation template file" 




later in this section. 



For C programmers, the SOM Compiler generates a <fi/estem>.G file. For C++ programmers, the SOM Compiler generates a <fi/estem>.C 
file (for AIX) or a <///esten7>.cpp file (for OS/2). To specify whether the SOM Compiler should generate a C or C++ implementation 
template, set the value of the SMEMIT environment variable, or use the -s option when running the SOM Compiler. (See "The SOM 
Compiler" in Chapter 4, "SOM IDL and the SOM Compiler.") 

Note: As this chapter describes, a SOM class can be implemented by using C++ to define the instance variables introduced by the class 
and to define the procedures that implement the overridden and introduced methods of the class. Be aware, however, that the C++ 
class defined by the C++ usage bindings for a SOM class (described in Chapter 3) cannot be subclassed in C++ to create new C++ or 
SOM classes. [The reason why the C++ implementation of a SOM class involves the definition of C++ procedures (not C++ methods) 
to support SOM methods is that there is no language-neutral way to call a C++ method. Only C++ code can call C++ methods, and 
this calling code must be generated by the same compiler that generates the method code. In contrast, the method procedures that 
implement SOM methods must be callable from any language, without knowledge on the part of the object client as to which language 
is used to implement the resolved method procedure] 



The implementation template 



Consider the following IDL description of the "FHello" class: 

/(include <somobj.idl> 

interface Hello : SOMObject 
{ 

void sayHello (); 

// This method outputs the string "Hello, World!". 

}; 



From this IDL description, the SOM Compiler generates the following C implementation template, hello. c (a C++ implementation template, 
hello. C or hello. cpp, is identical except that the #/nc/ude d file is <hello.xih> rather than <hello.ih>): 

#define Hello_Class_Source 
/(include <hello.ih> 

/* 

* This method outputs the string "Hello, World!". 

*/ 



SOM_Scope void SOMLINK sayHello (Hello somSelf, Environment *ev) 
{ 

/* HelloData *somThis = HelloGetData (somSelf ) ; */ 
HelloMethodDebug ( "Hello" , "sayHello") ; 

} 



The first line defines the "Flello_Class_Source" symbol, which is used in the SOM-generated implementation header files for C to determine 
when to define various functions, such as "FlelloNewClass." For interfaces defined within a module, the directive "#define 
<className>_Class_Source" is replaced by the directive "#define SOM_Module_<moduleName>_Source". 

The second line (# include <hello.ih> for C, or #include <hello.xih> for C++) includes the SOM-generated 
implementation header file. This file defines a struct holding the class's instance variables, macros for accessing instance variables, macros 
for invoking parent methods, and so forth. 



Stub procedures for methods 



For each method introduced or overridden by the class, the implementation template includes a stub procedure - a procedure that is empty 
except for an in/t/a//zation statement, a debugging statement, and possibly a return statement. The stub procedure for a method is 
preceded by any comments that follow the method's declaration in the IDL specification. 

For method "sayFlello" above, the SOM Compiler generates the following prototype of the stub procedure: 




SOM_Scope void SOMLINK sayHello (Hello somSelf, Environment *ev) 



The "SOM_Scope" symbol is defined in the implementation header file as either "extern" or "static," as appropriate. The term "void" signifies 
the return type of method "sayHello". The "SOMLINK" symbol is defined by SOM; it represents the keyword needed to link to the C or C++ 
compiler, and its value is system-specific. Using the "SOMLINK" symbol allows the code to work with a variety of compilers without 
modification. 

Following the "SOMLINK” symbol is the name of the procedure that implements the method. If no functionprefix modifier has been 
specified for the class, then the procedure name is the same as the method name. If a functionprefix modifier is in effect, then the 
procedure name is generated by prepending the specified prefix to the method name. For example, if the class definition contained the 
following statement: 



functionprefix = xx_; 



then the prototype of the stub procedure for method "sayHello" would be: 

SOM_Scope void SOMLINK xx_sayHello (Hello somSelf, Environment *ev) 



The functionprefix can not be 

<classname>_ 



since this is used in method invocation macros defined by the C usage bindings. 

Following the procedure name is the formal parameter list for the method procedure. Because each SOM method always receives at least 
one argument (a pointer to the SOM object that responds to the method), the first parameter name in the prototype of each stub procedure 
is called somSelf. (The macros defined in the implementation header file rely on this convention.) The somSelf parameter is a pointer to an 
object that is an instance of the class being implemented (here, class "Hello") or an instance of a class derived from it. 

Unless the IDL specification of the class included the callstyle=oidl modifier, then the formal parameter list will include one or two additional 
parameters before the parameters declared in the IDL specification: an (Environment *ev) input/output parameter, which permits the return 
of exception information, and, if the IDL specification of the method includes a context specification, a (Context *ctx) input parameter. 

These parameters are prescribed by the CORBA standard. For more information on using the Environment and Context parameters, see 
the section entitled "Exceptions and error handling" in Chapter 3, "Using SOM Classes in Client Programs," and the book The Common 
Object Request Broker: Architecture and Specification , published by Object Management Group and X/Open. 

The first statement in the stub procedure for method "sayHello" is the statement: 

/* HelloData *somThis = HelloGetData (somSelf ) ; */ 



This statement is enclosed in comments only when the class does not introduce any instance variables. The purpose of this statement, for 
classes that do introduce instance variables, is to initialize a local variable ( somThis t that points to a structure representing the instance 
variables introduced by the class. The somThis pointer is used by the macros defined in the "Hello" implementation header file to access 
those instance variables. (These macros are described below.) In this example, the "Hello” class introduces no instance variables, so the 
statement is commented out. If instance variables are later added to a class that initially had none, then the comment characters can be 
removed if access to the variable is required. 

The "HelloData" type and the "HelloGetData” macro used to initialize the somThis pointer are defined in the implementation header file. 
Within a method procedure, class implementers can use the somThis pointer to access instance data, or they can use the convenience 
macros defined for accessing each instance variable, as described below. 

To implement a method so that it can modify a local copy of an object's instance data without affecting the object's real instance data, 
declare a variable of type <c/ass/\tame>Va\a (for example, "HelloData") and assign to it the structure that somThis points to: then make the 
somThis pointer point to the copy. For example: 

HelloData myCopy = *somThis; 
somThis = &myCopy; 



Next in the stub procedure for method "sayHello” is the statement: 

HelloMethodDebug ( "Hello" , "sayHello") ; 



This statement facilitates debugging . The "HelloMethodDebug" macro is defined in the implementation header file. It takes two arguments, a 
class name and a method name. If debugging is turned on (that is, if global variable SOM_TraceLevel is set to one in the calling program), 
the macro produces a message each time the method procedure is entered. (See the next Chapter 3, "Using SOM Classes in Client 





Programs," for information on debugging with SOM.) 

Debugging can be permanently disabled (regardless of the setting of the SOM_TraceLevel setting in the calling program) by redefining the 
<c/assName> MethodDebug macro to be SOM_NoTrace(c,m) following the #include directive for the implementation header file. (This can 
yield a slight performance improvement.) For example, to permanently disable debugging for the "Hello" class, insert the following lines in 
the hello. c implementation file following the line "#include hello. ih" (or "#include hello. xih,” for classes implemented in C++): 

#undef HelloMethodDebug 

#define HelloMethodDebug (c,m) SOM_NoTrace (c, m) 



The way in which the stub procedure ends is determined by whether the method is a new or an overriding method. 

• For non-overridina (newt methods , the stub procedure ends with a return statement funless the return type of the method is 
void). The class implementer should customize this return statement. 

• For overriding methods , the stub procedure ends bv making a "parent method call" for each of the class's parent classes. If the 
method has a return type that is not void, the last of these parent method calls is returned as the result of the method procedure. 
The class implementer can customize this return statement if needed (for example, if some other value is to be returned, or if the 
parent method calls should be made before the method procedure's own processing). See the next section for a discussion of 
parent method calls. 

If a classinit modifier was specified to designate a user-defined procedure that will initialize the "Hello" class object, as in the statement: 

classinit = HInit; 



then the implementation template file would include the following stub procedure for "HInit", in addition to the stub procedures for Hello's 
methods: 



void SOMLINK HInit (SOMClass *cls) 
{ 



This stub procedure is then filled in by the class implementer. If the class definition specifies a functionprefix modifier, the classinit 
procedure name is generated by prepending the specified prefix to the specified classinit name, as with other stub procedures. 



Extending the implementation template 



To implement a method, add code to the body of the stub procedure . In addition to standard C or C++ code, class implementers can also 
use any of the functions, methods, and macros SOM provides for manipulating classes and objects. Chapter 3, "Using SOM Classes in 
Client Programs," discusses these functions, methods, and macros. 

In addition to the functions, methods, and macros SOM provides for both class clients and class implementers, SOM provides two facilities 
especially for class implementers. They are for (1) accessing instance variables of the object responding to the method and (2) making 
parent method calls, as follows. 



Accessing internal instance variables 

To access internal instance variables, class implementers can use either of the following forms: 

_ var/ab/eName 
somThis-> var/ab/eName 

To access internal instance variables "a", "b", and "c", for example, the class implementer could use either _a, _b, and _c, or somThis->a, 
somThis->b, and somThis->c. These expressions can appear on either side of an assignment statement. The somThis pointer must be 
properly initialized in advance using the <c/assName> GetData procedure, as shown above. 



Instance variables can be accessed only within the implementation file of the class that introduces the instance variable, and not within the 




implementation of subclasses or within client programs. (To allow access to instance data from a subclass or from client programs, use an 
attribute rather than an instance variable to represent the instance data.) For C++ programmers, th q _variab/ef/ame form is available only if 
the macro VARIABLE_MACROS is defined (that is, #define VARIABLEMACROS) in the implementation file prior to including the .xih file 
for the class. 



Making parent method calls 



In addition to macros for accessing instance variables, the implementation header file that the SOM Compiler generates also contains 
definitions of macros for making "parent method calls ." When a class overrides a method defined by one or more of its parent classes, often 
the new implementation simply needs to augment the functionality of the existing implementation(s). Rather than completely 
re-implementing the method, the overriding method procedure can conveniently invoke the procedure that one or more of the parent classes 
uses to implement that method, then perform additional computation (redefinition) as needed. The parent method call can occur anywhere 
within the overriding method. (See Example 3 of the SOM IDL tutorial.) 

The SOM-generated implementation header file defines the following macros for making parent-method calls from within an overriding 
method: 

< c/assName >_pa xwc\\_<parentC/assName >_< methodName > 

(for each parent class of the class overriding 
the method), and 

< c/asst/ame >_p arents_< methodName > . 

For example, given class "Hello" with parents "File" and "Printer" and overriding method somlnit (the SOM method that initializes each 
object), the SOM Compiler defines the following macros in the implementation header file for "Hello": 

Hello_parent_Printer_somInit 

Hello_parent_File_somInit 

Hello_parents_somInit 



Each macro takes the same number and type of arguments as <method/\/ame>. The 

<c/ass/\tame>jgwew\_<parentC/ass/\/ame>_<method/\/ame> macro invokes the implementation of <methodName> inherited from 
<parentC/assName>. Hence, using the macro "Hello_parent_File_somlnit" invokes the File's implementation of somlnit. 

The <c/assA/ame>jpaxen\s_< method/\/ame> macro invokes the parent method for each parent of the child class that supports 
<methodName>. That is, "Hello_parents_somlnit" would invoke File's implementation of somlnit, followed by Printer's implementation of 
somlnit. The <c/ass/Vame>gpateY\\s_<metbod/\/ame> macro is redefined in the binding file each time the class interface is modified, so 
that if a parent class is added or removed from the class definition, or if <method/\/ame> is added to one of the existing parents, the macro 
<c/assName>jpax&r\\s_<methodName > will be redefined appropriately. 



Converting C++ classes to SOM classes 



For C++ programmers implementing SOM classes, SOM provides a macro that simplifies the process of converting C++ classes to SOM 
classes. This macro allows the implementation of one method of a class to invoke another new or overriding method of the same class on 
the same receiving object by using the following shorthand syntax: 

_methodName (argl , arg2, ...) 



For example, if class ^introduces or overrides methods ml and m2 , then the C++ implementation of method ml can invoke method m2 
on its somSe/f argument using _m2farg, arg2, ... ), rather than somSe/f->m2fargt, arg2, ...J, as would otherwise be required. (The longer 
form is also available.) Before the shorthand form in the implementation file is used, the macro METHOD_MACROS must be defined (that 
is, use #define METHOD_MACROS) prior to including the xih file for the class. 



Running incremental updates of the implementation template 




file 



Refining the .idl file for a class is typically an iterative process. For example, after running the IDL source file through the SOM Compiler and 
writing some code in the implementation template file, the class implementer realizes that the IDL class interface needs another method or 
attribute, a method needs a different parameter, or any such changes. 

As mentioned earlier, the SOM Compiler (when run using the c or xc emitter) assists in this development by reprocessing the .idl file and 
making incremental updates to the current implementation file. This modify-and-update process may in fact be repeated several times 
before the class declaration becomes final. Importantly, these updates do not disturb existing code for the method procedures. Included in 
the incremental update are these changes: 

• Stub procedures are inserted into the implementation file for any new methods added to the .idl file. 

• New comments in the .idl file are transferred to the implementation file, reformatted appropriately. 

• If the interface to a method has changed, a new method procedure prototype is placed in the implementation file. As a 
precaution, however, the old prototype is also preserved within comments. The body of the method procedure is left untouched 
(as are the method procedures for all methods). 

• Similarly left intact are preprocessor directives, data declarations, constant declarations, non-method functions, and additional 
comments-in essence, everything else in the implementation file. 

Some changes to the .idl file are not reflected automatically in the implementation file after an incremental update. The class implementer 
must manually edit the implementation file after changes such as these in the .idl file: 

• Changing the name of a class or a method. 

• Changing the parents of a class (see also "If you change the parents of a class..." later in this topic). 

• Changing a functionprefix class modifier statement. 

• Changing the content of a passthru statement directed to the implementation (.c, .C, or cpp) file. As previously emphasized, 
however, passthru statements are primarily recommended only for placing #include statements in a binding file (.ih, xih, ,h, or 
.xh file) used as a header file in the implementation file or in a client program. 

• If the class implementer has placed "forward declarations" of the method procedures in the implementation file, those are not 
updated. Updates occur only for method prototypes that are part of the method procedures themselves. 



Considerations to ensure that updates work 



To ensure that the SOM Compiler can properly update method procedure prototypes in the implementation file, class implementers should 
avoid editing changes such as the following: 

• A method procedure name should not be enclosed in parentheses in the prototype. 

• A method procedure name must appear in the first line of the prototype, excluding comments and white space. Thus, a new line 
must not be inserted before the procedure name. 

Error messages occur while updating an existing implementation file if it contains syntax that is not ANSI C. For example, "old style" method 
definitions such as the example on the left generate errors: 

Invalid "old" syntax Required ANSI C 

void foo (x) void foo (short x) { 

short x; 

{ } 



} 

Similarly, error messages occur if anything in the .idl file would produce an implementation file that is not syntactically valid for C/C++ (such 
as nested comments). If update errors occur, either the .idl file or the implementation file may be at fault. One way to track down the problem 
is to run the implementation file through the C/C++ compiler. Or, move the existing implementation file to another directory, generate a 
completely new one from the .idl file, and then run it through the C/C++ compiler. One of these steps should pinpoint the error, if the 
compiler is strict ANSI. 




Conditional compilation (using #if and #ifdef directives) in the implementation file can be another source of errors, because the SOM 
Compiler does not invoke the preprocessor (it simply recognizes and ignores those directives). The programmer should be careful when 
using conditional compilation, to avoid a situation such as shown below; here, with apparently two open braces and only one closing brace, 
the c or xc emitter would report an unexpected end-of-file: 

Invalid syntax Required matching braces 

#ifdef FOOBAR #ifdef FOOBAR 

{ { 



#else 

{ 



#endif 



} 

#else 

{ 



#endif 



If you change the parents of a class... 



Because the implementation-file emitters never change any existing code within a previously generated implementation file, changing the 
parents of a class requires extremely careful attention by the programmer. For example, for overridden methods, changing a class's parents 
may invalidate previous parent-method calls provided by the template, and require the addition of new parent-method calls. Neither of these 
issues is addressed by the incremental update of previously generated method-procedure templates. 

The greatest danger from changing the parents of a class, however, concerns the ancestor-initializer calls provided in the stub procedures 
for initializer methods. (For further information on ancestor initializer calls, see "Initializing and Uninitializing Objects” later in this chapter.) 
Unlike parent-method calls, ancestor-initializer calls are not optional - they must be made t all classes specified in a directinitclasses 
modifier, and these calls should always include the parents of the class (the default when no directinitclasses modifier is given). When the 
parents of a class are changed, however, the ancestor-initializer calls (which must be made in a specific order) are not updated. 

The easiest way to deal with this problem is to change the method name of the previously generated initializer stub procedure in the 
implementation template file. Then, the SOM Compiler can correctly generate a completely new initializer stub procedure (while ignoring the 
renamed procedure). Once this is done, your customization code from the renamed initializer procedure can be "merged" into the newly 
generated one, after which the renamed initializer procedure can be deleted. 



Compiling and linking 



After you fill in the method stub procedures, the implementation template file can be compiled and linked with a client program as follows. (In 
these examples, the environment variable SOMBASE represents the directory in which SOM has been installed.) 

Note: If you are building an application that uses a combination of C and C++ compiled object modules, then the C++ linker must be used to 
link them. 

For AIX : When the client program (main.c) and the implementation file (hello. c) are written in C: 

> xlc -I. -I$SOMBASE/include -o hello main.c hello. c -L$SOMBASE/lib -lsomtk 

When the client program and the implementation file are written in C++: 

> xlc -I. -I$SOMBASE/ include -o hello main.c hello. C -L$SOMBASE/ lib -lsomtk 

For OS/2 : When the client program (main.c) and the implementation file (hello. c) are in C: 

> set LIB=%SOMBASE%\lib; %LIB% 

> icc -I. -I%SOMBASE%\include -Fe hello main.c hello. c somtk.lib 



When the client program and the implementation file are written in C++: 




> set LIB=%SOMBASE%\lib; %LIB% 

> icc -I. -I%SOMBASE%\include -Fe hello main.cpp hello. cpp somtk.lib 

If the class definition (in the .idl file) changes, run the SOM Compiler again. This will generate new header files , and it will update the 
implementation file to include any: 

• New comments, 

• Stub procedures for any new methods, and 

• Revised method procedure prototypes for methods whose signatures have been changed in the .idl file. 

After rerunning the SOM Compiler, add to the implementation file the code for any newly added method procedures, and recompile the 
implementation file with the client program. 



Initializing and Uninitializing Objects 



This section discusses the initialization and uninitialization of SOM objects. Subsequent topics introduce the methods and capabilities that 
the SOMobjects Developer Toolkit provides to facilitate this. 

Object creation is the act that enables the execution of methods on an object. In SOM, this means storing a pointer to a method table into a 
word of memory. This single act converts raw memory into an (uninitialized) SOM object that starts at the location of the method table 
pointer. 

Object initia/ization, on the other hand, is a separate activity from object creation in SOM. Initialization is a capability supported by certain 
methods available on an object. An object's class determines the implementation of the methods available on the object, and thus 
determines its initialization behavior. 

The instance variables encapsulated by a newly created object must be brought into a consistent state before the object can be used. This 
is the purpose of init/at/zation methods. Because, in general, every ancestor of an object's class contributes instance data to an object, it is 
appropriate that each of these ancestors contribute to the initialization of the object. 

SOM thus recognizes init/a/izers as a special kind of method. One advantage of this approach is that special metaclasses are not required 
for defining constructors (class methods) that take arguments. Furthermore, a class can define multiple initializer methods, thus enabling its 
different objects to be initialized supporting different characteristics or capabilities. This results in simpler designs and more efficient 
programs. 

The SOMobjects Toolkit provides an overall framework that class designers can easily exploit in order to implement default or customized 
initialization of SOM objects. This framework is fully supported by the SOM Toolkit emitters that produce the implementation template file. 
The following sections describe the declaration, implementation, and use of initializer (and uninitializer) methods. 

Important: All code written prior to SOMobjects Release 2.1 using documented guidelines for the earlier initialization approach based on the 
somlnit method (as well as all existing class binaries) continues to be fully supported and useful. 



Initializer methods 



As noted above, in the SOMobjects Toolkit each ancestor of an object contributes to the initialization of that object. Initialization of an object 
involves a chain of ancestor-method calls that, by default, are automatically determined by the SOM Compiler emitters. The SOMobjects 
framework for initialization of objects is based on the following approach: 

1 . SOMobjects recognizes initializers as a special kind of method, and supports a special mechanism for ordering the execution of 
ancestor-initializer method procedures. The SOMObject class introduces an initializer method, somDefaultlnit that uses this 
execution mechanism. 

2. The SOM Compiler's emitters provide special support for methods that are declared as initializers in the .idl file. To supplement 
the somDefaultlnit method, SOM class designers can also declare additional initializers in their own classes. 

Two SOM IDL modifiers are provided for declaring initializer methods and controlling their execution, init and directinitclasses: 



The init modifier is required in order to designate a given method is a initializer; that is, to indicate that the method both uses and 




supports the object-initialization protocol described here. 



• The directinitclasses modifier can be used to control the order of execution of initializer method procedures provided by the 
different ancestors of the class of an object. 

• For full definitions of init and directinitclasses, see the topic "Modifier statements" in Chapter 4, "SOM IDL and the SOM 
Compiler.” 

Every SOM class has a list that defines (in sequential order) the ancestor classes whose initializer method procedures the class should 
invoke. If a class's IDL does not specify an explicit directinitclasses modifier, the default for this list is simply the class's parents - in 
left-to-right order. 

Using the directinitclasses list and the actual run-time class hierarchy above itself, each class inherits from SOMCIass the ability to create 
a data structure of type somlnitCtrl. This structure is used to control the execution of initializers. Moreover, it represents a particular 
visit-ordering that reaches each class in the transitive closure of directinitclasses exactly once. To initialize a given object, this 
visit-ordering occurs as follows: While recursively visiting each ancestor class whose initializer method procedure should be run, 
SOMobjects first runs the initializer method procedures of all of that class's directinitclasses if they have not already been run by another 
class's initializers, with ancestor classes always taken in left-to-right order. 

The code that deals with the somlnitCtrl data structure is generated automatically within the implementation bindings for a class, and need 
not concern a class implementor. 

When an instance of a given class (or some descendant class) is initialized, only one of the given class's initializers will be executed, and 
this will happen exactly once (under control of the ordering determined by the class of the object being initialized). 

The somlnitCtrl structure solves a problem originally created by the add ition of multiple inheritance to SOMobjects 2.0. With 

multiple inheritance, any class can appear at the top of a multiple inheritance diamond. Previously, whenever this happened, the class could 
easily receive multiple initialization calls. In the current version of the SOMobjects Toolkit, however, the somlnitCtrl structure prevents this 
from happening. 



Declaring new initializers in SOM IDL 



When defining SOMobjects classes, programmers can easily declare and implement new initializers. Classes can have as many initializers 
as desired, and subclassers can invoke whichever of these they want. When introducing new initializers, developers must adhere to the 
following rules: 

• All initializer methods take a somlnitCtrl data structure as an initial inout parameter (its type is defined in the SOMobjects 
header file somapi.h), and 

• All initializers return void. 

Accordingly, the somDefaultlnit initializer introduced by SOMObject takes a somlnitCtrl structure as its (only) argument, and returns void. 
Plere is the IDL syntax for this method, as declared in somobj.idl: 

void somDefaultlnit (inout somlnitCtrl Ctrl) ; 



When introducing a new initializer, it is also necessary to specify the init modifier in the implementation section. The init modifier is what 
tells emitters that the new method is actually an initializer, so the method can be properly supported from the language bindings. As 
described below, this support includes the generation of special initializer stub procedures in the implementation template file, as well as 
bindings containing ancestor-initialization macros and object constructors that invoke the class implementor's new initializers. 

It is a good idea to begin the names of initializer methods with the name of the class (or some other string that can be unique for the class). 
This is important because all initializers available on a class must be newly introduced by that class (that is, you cannot override initializers - 
except for somDefaultlnit). Using a class-unique name means that subclasses will not be unnecessarily constrained in their choice of 
initializer names. 

Flere are two classes that introduce new initializers: 



interface Examplel : SOMObject 
{ 

void Example l_withName (inout somlnitCtrl 
void Examplel_withSize (inout somlnitCtrl 
void Example l_withNandS ( inout somlnitCtrl 



Ctrl, in string name); 
Ctrl, in long size); 
Ctrl, in string name, 
in long size) ; 



implementation { 

releaseorder : Examplel_withName, 
Example l_withSize, 




Examplel_withNandS ; 

somDefaultlnit: override, init; 
somDestruct: override; 

Examplel_withName : init; 
Examplel_withSize : init; 
Examplel_withNandS : init; 



interface Example2 : Examplel 
{ 

void Example2_withName (inout somlnitCtrl Ctrl, in string name) ; 
void Example2_withSize (inout somlnitCtrl Ctrl, in long size); 
implementation { 

releaseorder : Example2_withName, 

Example2_withSize; 

somDefaultlnit: override, init; 
somDestruct: override; 

Example2_withName : init; 

Example2_withSize : init; 




Here, interface "Examplel" declares three new initializers. Notice the use of inout somlnitCtrl as the first argument of each initializer, and 
also note that the init modifier is used in the implementation section. These two things are required to declare initializers. Any number of 
initializers can be declared by a class. "Example2" declares two initializers. 

"Examplel" and "Example2" both override the somDefaultlnit initializerThis initializer method is introduced by SOMObject and is special 
for two resons: First, somDefaultlnit is the only initializer that can be overridden And, second, SOMobjects arranges that this initializer will 
always be available on any class (as further explained below). 

Historically in the SOMobjects Toolkit, object#initialization methods by default have invoked the somlnit method, which class implementors 
could override to customize initialization as appropriate. SOMobjects continues to support this approach, so that existing code (and class 
binaries) will execute correctly. However, the somDefaultlnit method is now the preferred form of initialization because it offers greatly 
improved efficiency. 

Even if no specialized initialization is needed for a class, you should still override the somDefaultlnit method in the interest of efficiency. If 
you do not override somDefaultlnit, then a generic (and therefore less efficient) somDefaultlnit method procedure will be used for your 
class. This generic method procedure first invokes somDefaultlnit on the appropriate ancestor classes. Then (for consistency with earlier 
versions of SOMobjects), it checks to determine if the class overrides somlnit and, if so, calls any customized somlnit code provided by the 
class. 

When you override somDefaultlnit, the emitter's implementation template file will include a stub procedure similar to those used for other 
initializers, and you can fill it in as appropriate (or simply leave it as is). Default initialization for your class will then run much faster than with 
the generic method procedure. Examples of initializer stub procedures (and customizations) are given below. 

In summary, the initializers available for any class of objects are somDefaultlnit (which you should always override) plus any new 
initializers explicitly declared by the class designer. Thus, "Examplel" objects may be initialized using any of four different initializers (the 
three that are explicitly declared, plus somDefaultlnit). Likewise, there are three initializers for the "Example2" objects. Some examples of 
using initializers are provided below. 



Considerations re: 'somlnit' initialization from earlier SOM 
releases 

To re-emphasize: All code written prior to SOMobjects Release 2.1 using documented guidelines for the earlier initialization approach 
based on the somlnit method (as well as all existing class binaries) continues to be fully supported and useful. 

Prior to SOMobjects 2.1 , initialization was done with initializer methods that would simply "chain" parent-method calls upward, thereby 
allowing the execution of initializer method procedures contributed by all ancestors of an object's class. This chaining of initializer calls was 
not supported in any special way by the SOM API. Parent-method calls are simply one of the possible idioms available to users of OOP in 
SOM, easily available to a SOM class designer as a result of the support provided by the SOMobjects Toolkit emitters for parent-method 
calls. 



So, SOM did not constrain initialization to be done in any particular way or require the use of any particular ordering of the method 




procedures of ancestor classes. But, SOM did provide an overall framework that class designers could easily utilize in order to implement 
default initialization of SOM objects. This framework is provided by the somlnit object-initializatio method introduced by the SOMobject 
class and supported by the SOM Toolkit emitters. The emitters create an implementation template file with stub procedures for overridden 
methods that automatically chain parent-method calls upward through parent classes. Many of the class methods that perform object 
creation called somlnit automatically. 

Note: These will now call somDefaultlnit, which in turn calls somlnit for legacy code, as described in the previous topic. 



Because it takes no arguments, somlnit best served the purpose of a default initializer. SOM programmers also had the option of 
introducing additional ''non-default" initialization methods that took arguments. In addition, by using metaclasses, they could introduce new 
class methods as object constructors that first create an object (generally using somNewNolnit.) and then invoke some non-default 
initializer on the new object. 

For a number of reasons, the somlnit framework has been augmented by recognizing /nitia/izers special kind of method in SOMobjects. 
One advantage of this approach is that special metaclasses are no longer required for defining constructors that take arguments. Instead, 
because the init modifier identifies initializers, usage-binding emitters can now provide these constructors. This results in simpler designs 
and more efficient programs. 

Although somDefaultlnit replaces somlnit as the no-argument initializer used for SOM objects, all previous use of somlnit is still supported 
by the SOMobjects Developers Toolkit on AIX, OS/2 and 16-bit Windows. You may continue to use somlnit on these systems if you like, 
although this is somewhat less efficient than using somDefaultlnit. 

Flowever, you cannot use both methods. In particular, if a class overrides both somDefaultlnit and somlnit, its somlnit code will never be 
executed. It is recommended that you always override somDefaultlnit for object initialization. For one thing, it is likely that when 
SOMobjects is ported to new systems, somlnit (and somUninit) may not be supported on those systems. Thus, code written using these 
(obsolete) methods will be less portable. 



Implementing initializers 



When new initializers are introduced by a class, as in the preceding examples, the implementation template file generated by the SOM 
Toolkit C and C++ emitters automatically contains an appropriate stub procedure for each initializer method, for the class implementor's use. 
The body of an initializer stub procedure consists of two main sections: 

• The first section performs calls to ancestors of the class to invoke their initializers. 

• The second section is used by the programmer to perform any "local” initializations appropriate to the instance data of the class 
being defined. 

In the first section, by default, the parents of the new class are the ancestors whose initializers are called. When something else is desired, 
the IDL directinitclasses modifier can be used to explicitly designate the ancestors whose initializer methods should be invoked by a new 
class's initializers. 

Important: Under no circumstances can the number or the ordering of ancestor initializer calls in the first section of an initializer stub 
procedure be changed. The control masks used by initializers are based on these orderings. (If you want to change the number or ordering 
of ancestor initializer calls, you must use the directinitclasses modifier.) The ancestor initializer calls themselves can be modified as 
described below. 

Each call to an ancestor initializer is made using a special macro (much like a parent call) that is defined for this purpose within the 
implementation bindings. These macros are defined for all possible ancestor initialization calls. Initially, an initializer stub procedure invokes 
the default ancestor initializers provided by somDefaultlnit. Flowever, a class implementor can replace any of these calls with a different 
initializer call, as long as it calls the same ancestor (see the example in the next topic). Non-default initializer calls generally take other 
arguments in addition to the control argument. 

In the second section of an initializer stub procedure, the programmer provides any class-specific code that may be needed for initialization. 
For example, the "Example2_withName" stub procedure is shown below. As with all stub procedures produced by the SOMobjects 
implementation-template emitters, this code requires no modification to run correctly. 

SOM_Scope void SOMLINK Example2_withName (Example2 *somSelf, 

Environment *ev, 
somlnitCtrl* Ctrl, 
string name) 

{ 

Example2Data *somThis; /* set by Beginlnitializer */ 
somlnitCtrl globalCtrl; 
somBooleanVector myMask; 

Example2MethodDebug ( "Example2 " , "withName") ; 




/* 

* first section — calls to ancestor initializers 
*/ 

Example2_BeginInitializer_Example2_withName; 
Example2_Init_Examplel_somDef aultlnit (somSelf , Ctrl) ; 

/* 

* second section — local Example2 initialization code 
*/ 



In this example, notice that the "Example2_withName" initializer is an IDL callstyle method, so it receives an Environment argument. In 
contrast, somDefaultlnit is introduced by the SOMObject class (so it has an OIDL callstyle initializer, without an environment). 

Important: If a class is defined where multiple initializers have exactly the same signature, then the C++ usage bindings will not be able to 
differentiate among them. That is, if there are multiple initializers defined with environment and long arguments, for example, then C++ 
clients would not be able to make a call using only the class name and arguments, such as: 



new Example2 (env, 123) ; 



Rather, C++ users would be forced to first invoke the somNewNolnit method on the class to create an uninitialized object, and then 
separately invoke the desired initializer method on the object. This call would pass a zero for the control argument, in addition to passing 
values for the other arguments. For further discussion of client usage, see "Using initializers when creating new objects" later in this chapter. 



Selecting non-default ancestor initializer calls 



Often, it will be appropriate (in the first section of an initializer stub procedure) to change the invocation of an ancestor's somDefaultlnit 
initializer to some other initializer available on the same class. The rule for making this change is simple: Replace somDefaultlnit with the 
name of the desired ancestor initializer, and add any new arguments that are required by the replacement initializer. Important: Under no 
circumstances can you change anything else in the first section. 

This example shows how to change an ancestor-initializer call correctly. Since there is a known "Example1_withName'' initializer, the 
following default ancestor-initializer call (produced within the stub procedure for "Example2_withName") can be changed from 



Example2_Init_Examplel__somDefaultInit (somSelf , Ctrl) ; 
to 

Example2_Init_Examplel_Examplel_withName ( somSelf , ev, Ctrl, name) 



Notice that the revised ancestor-initializer call includes arguments for an Environment and a name, as defined by the 
"Examplel _withname" initializer. 



Using initializers when creating new objects 



There are several ways that client programs can take advantage of the somDefaultlnit object initialization. If desired, clients can use the 
SOM API directly (rather than taking advantage of the usage bindings). Also, the general object constructor, somNew, can always be 
invoked on a class to create and initialize objects. This call creates a new object and then invokes somDefaultlnit on it 

To use the SOM API directly, the client code should first invoke the somNewNolnit method on the desired class object to create a new, 
uninitialized object. Then, the desired initializer is invoked on the new object, passing a null (that is, 0) control argument in addition to 
whatever other arguments may be required by the initializer. For example: 



/* first make sure the Example2 class object exists */ 
Example2NewClass (Example2_Ma jorVersion, Example2_MinorVersion) ; 




/* then create a new, uninitialized Example2 object */ 
myObject = _somNewNoInit (_Example2 ) ; 

(null) 

/* then initialize it with the desired initializer */ 
Example2_withName (myObject , env, 0, "MyName"); 



Usage bindings hide the details associated with initializer use in various ways and make calls more convenient for the client. For example, 
the C usage bindings for any given class already provide a convenience macro, <c/assName> New, that first assures existence of the class 
object, and then calls somNew on it to create and initialize a new object. As explained above, somNew will use somDefaultlnit to initialize 
the new object. 

Also, the C usage bindings provide object-construction macros that use somNewNolnit and then invoke non-default initializers. These 
macros are named using the form <c/assName>W&N_<in/tia/izerName>. For example, the C usage bindings for "Example2" allow using the 
following expression to create, initialize, and return a new "Example2" object: 



Example2New_Example2_withName (env, "AnyName") ; 



In the C++ bindings, initializers are represented as overloaded C++ constructors. As a result, there is no need to specify the name of the 
initializer method. For example, using the C++ bindings, the following expressions could be used to create a new "Example2" object: 



new 


Examp le2 ; 


// 


will 


use 


somDefaultlnit 


new 


Example2 ( ) ; 


// 


will 


use 


somDefaultlnit 


new 


Example2 (env, " A. B. Normal") 


; // 


will 


use 


Example2_withName 


new 


Example2 (env, 123) ; 


// 


will 


use 


Example2_withSize 



Observe that if multiple initializers in a class have exactly the same signatures, the C++ usage bindings would be unable to differentiate 
among the calls, if made using the forms illustrated above. In this case, a client could use somNewNolnit first, and then invoke the specific 
initializer, as described in the preceding paragraphs. 



Uninitialization 



An object should always be uninitialized before its storage is freed. This is important because it also allows releasing resources and freeing 
storage not contained within the body of the object. SOMobjects handles uninitialization in much the same way as for initializers: An 
uninitializer takes a control argument and is supported with stub procedures in the implementation template file in a manner similar to 
initializers. 

Only a single uninitialization method is needed, so SOMObject introduces the method that provides this function: somDestruct. As with the 
default initializer method, a class designer who requires nothing special in the way of uninitialization need not be concerned about modifying 
the default somDestruct method procedure. Flowever, your code will execute faster if the .idl file overrides somDestruct so that a 
non-generic stub-procedure code can be provided for the class. Note that somDestruct was overridden by "Examplel " and ”Example2" 
above No specific IDL modifiers other than override are required for this. 

Like an initializer template, the stub procedure for somDestruct consists of two sections: The first section is used by the programmer for 
performing any ''local" uninitialization that may be required. The second section (which consists of a single EndDestructor macro 
invocation) invokes somDestruct on ancestors The second section must not be modified or removed by the programmer. It must be the 
final statement executed in the destructor. 



Using 'somDestruct' 



It is rarely necessary to invoke the somDestruct method explicitly This is because object uninitialization is normally done just before freeing 
an object's storage, and the mechanisms provided by SOMobjects for this purpose will automatically invoke somDestruct. For example, if 
an object were created using somNew or somNewNolnit, or by using a convenience macro provided by the C languag bindings, then the 
somFree method can be invoked on the object to delete the object. This automatically calls somDestruct before freeing storage. 



C++ users can simply use the delete operator provided by the C++ bindings. This destructor calls somDestruct before the C++ delete 
operator frees the object's storage. 




On the other hand, if an object is initially created by allocating memory in some special way and subsequently some somRenew methods 
are used, somFree (or C++ delete) is probably not appropriate. Thus, the somDestruct method should be explicitly called to uninitialize the 
object before freeing memory. 



A complete example 



The following example illustrates the implementation and use of initializers and destructors from the C++ bindings. The first part shows the 
IDL for three classes with initializers. For variety, some of the classes use callstyle OIDL and others use callstyle IDL. 

#include <somobj.idl> 

interface A : SOMObject { 

readonly attribute long a; 
implementation { 

releaseorder : _get_a; 
functionpref ix = A; 
somDef aultlnit : override, init; 
somDestruct: override; 
somPrintSelf : override; 




(null) 

interface B : SOMObject { 

readonly attribute long b; 

void BwithlnitialValue (inout somlnitCtrl Ctrl, 

in long initialValue) ; 

implementation { 

callstyle = oidl; 

releaseorder: _get_b, BwithlnitialValue; 
functionpref ix = B; 

BwithlnitialValue: init; 
somDef aultlnit : override, init; 
somDestruct: override; 

somPrintSelf: override; 




(null) 

interface C : A, B { 

readonly attribute long c; 

void CwithlnitialValue (inout somlnitCtrl Ctrl, 

in long initialValue) ; 

void CwithlnitialString ( inout somlnitCtrl Ctrl, 

in string initialstring) ; 

implementation { 

releaseorder: _get_c, CwithlnitialString, 
CwithlnitialValue; 
functionpref ix = C; 

CwithlnitialString: init; 
CwithlnitialValue: init; 
somDef aultlnit : override; 
somDestruct: override; 

somPrintSelf: override; 




Implementation code 




Based on the foregoing class definitions, the next example illustrates several important aspects of initializers. The following code is a 
completed implementation template and an example client program for the preceding classes. Code added to the original template is given 
in bold. 



/* 

* This file generated by the SOM Compiler and Emitter Framework. 

* Generated using: 

* SOM Emitter emitxtm.dll: 2.22 
*/ 

#def ine SOM_Module_ctorfullexample_Source 
#def ine VAR I AB L E_MAC RO S 
#def ine METHOD_MACROS 
#include <ctorFullExample . xih> 

#include <stdio.h> 



SOM_Scope void SOMLINK AsomDef ault Init (A *somSelf , 

somlnitCtrl* 



AData *somThis; /* set by Beginlnitializer */ 
somlnitCtrl globalCtrl; 
somBooleanVector myMask; 

AMethodDebug ( "A" , "somDef ault Init") ; 



Ctrl) 



A_Begin I ni t i alizer_somDe fault Init ; 

A_Init_SOMOb ject_somDef aultlnit (somSelf , Ctrl) ; 

/* 

* local A initialization code added by programmer 
*/ 

a = 1 ; 

} 



SOM_Scope void SOMLINK AsomDestruct (A *somSelf , octet doFree, 

somDestructCtrl* Ctrl) 



AData *somThis; /* set by BeginDestructor */ 
somDestructCtrl globalCtrl; 
somBooleanVector myMask; 

AMethodDebug ( "A" , "somDestruct") ; 

A_BeginDe struct or ; 



/* 

* local A deinitialization code added by programmer 
*/ 

A_EndDestructor ; 



SOM_Scope SOMObject* SOMLINK AsomPrintSelf (A *somSelf) 

{ 

AData *somThis = AGetData (somSelf ) ; 

AMethodDebug ( "A" , " somPrintSelf " ) ; 

somPrintf ( " {an instance of %s at location %X with (a=%d)}\n", 

_somGetClassName () , somSelf, get_a ( (Environment*) 0) ) ; 

return (SOMObject*) ( (void*) somSelf ) ; 

} 



SOM_Scope void SOMLINK BBwithlnitialValue (B *somSelf, 

somlnitCtrl* Ctrl, 
long initialValue) 

{ 

BData *somThis; /* set by Beginlnitializer */ 
somlnitCtrl globalCtrl; 
somBooleanVector myMask; 

BMethodDebug ( "B" , "BwithlnitialValue" ) ; 

B_BeginInitializer_withInitialValue; 
B_Init_SOMObject_somDef aultlnit (somSelf, Ctrl) ; 

/* 

* local B initialization code added by programmer 
*/ 

_b = initialValue; 




SOM_Scope void SOMLINK BsomDef ault Init (B *somSelf , 

somlnitCtrl* 



BData *somThis; /* set by Beginlnitializer */ 
somlnitCtrl globalCtrl; 
somBooleanVector myMask; 

BMethodDebug ( "B" , "somDef ault Init") ; 



Ctrl) 



B_Begin I ni t i alizer_somDe fault Init ; 

B_Init_SOMOb ject_somDef aultlnit (somSelf , Ctrl) ; 

/* 

* local B initialization code added by programmer 
*/ 

__b = 2; 

} 



SOM_Scope void SOMLINK BsomDestruct (B *somSelf , octet doFree, 

somDestructCtrl* Ctrl) 



BData *somThis; /* set by BeginDestructor */ 
somDestructCtrl globalCtrl; 
somBooleanVector myMask; 

BMethodDebug ( "B" , "somDestruct") ; 
B_BeginDestructor ; 



/* 

* local B deinitialization code added by programmer 
*/ 



B_EndDestructor ; 

} 



SOM_Scope SOMOb ject* SOMLINK BsomPrintSelf (B *somSelf) 

{ 

BData *somThis = BGetData (somSelf ) ; 

BMethodDebug ( "B" , "somPrintSelf " ) ; 

printf("{an instance of %s at location %X with (b=%d)}\n", 

_somGetClassName ( ) , somSelf, get_b ( ) ) ; 

return (SOMObject*) ( (void*) somSelf ) ; 

} 



Note: The following initializer for a C object accepts a string as an argument, converts this to an integer, and uses this for ancestor 
initialization of "B." This illustrates how a default ancestor initializer call is replaced with a non-default ancestor initializer call. 

SOM_Scope void SOMLINK CCwithlnitialString (C *somSelf, 

Environment *ev, 
somlnitCtrl* Ctrl, 
string initialstring) 

{ 

CData *somThis; /* set by Beginlnitializer */ 
somlnitCtrl globalCtrl; 
somBooleanVector myMask; 

CMethodDebug ( "C" , "CwithlnitialString" ) ; 

C_BeginInitializer_withInitialString; 

C_Init_A_somDef aultlnit (somSelf, Ctrl) ; 

C_Init_B_BwithInitialValue (somSelf, Ctrl, 

atoi (initialstring) -11) ; 



/* 

* local C initialization code added by programmer 
*/ 

_c = atoi (initialstring) ; 



SOM_Scope void SOMLINK CsomDef ault Init (C *somSelf , 




{ 



somlnitCtrl* Ctrl) 

CData *somThis; /* set by Beginlnitializer */ 
somlnitCtrl globalCtrl; 
somBooleanVector myMask; 

CMethodDebug ( "C" , "somDefaultlnit " ) ; 



C_BeginInitializer_somDef aultlnit ; 
C_Init_A_somDef aultlnit (somSelf , Ctrl) ; 
C_Init_B_somDef aultlnit (somSelf, Ctrl) ; 



/* 

* local C initialization code added by programmer 
*/ 

c = 3; 

} 



SOM_Scope void SOMLINK CsomDestruct (C *somSelf , octet doFree, 

somDestructCtrl* Ctrl) 



CData *somThis; /* set by BeginDestructor */ 
somDestructCtrl globalCtrl; 
somBooleanVector myMask; 

CMethodDebug ( "C" , "somDestruct") ; 

C_BeginDe struct or ; 



/* 

* local C deinitialization code added by programmer 
*/ 



C_EndDe struct or ; 

} 



SOM_Scope SOMObject* SOMLINK CsomPrintSelf (C *somSelf) 
{ 



CData *somThis = CGetData (somSelf ) ; 

CMethodDebug ( "C" , "somPrintSelf " ) ; 

printf("{an instance of %s at location %X with" 
" (a=%d, b=%d, c=%d) } \n " , 
_somGetClassName () , somSelf, 

get_a ( (Environment*) 0) , 

get b ( ) , 

get_c ( (Environment*) 0) ) ; 

return (SOMObject*) ( (void*) somSelf ) ; 



SOM_Scope void SOMLINK CCwithlnitialValue ( C *somSelf, 

Environment *ev, 
somlnitCtrl* Ctrl, 
long initialValue) 

{ 

CData *somThis; /* set by Beginlnitializer */ 
somlnitCtrl globalCtrl; 
somBooleanVector myMask; 

CMethodDebug ( "C" , "CwithlnitialValue" ) ; 

C_BeginInitializer_withInitialValue; 

C_Init_A_somDef aultlnit (somSelf, Ctrl) ; 

C_Init_B_BwithInitialValue (somSelf , Ctrl, initialValue-11) ; 

/* 

* local C initialization code added by programmer 
*/ 

_c = initialValue; 

} 



Here is a C++ program that creates instances of "A", "B", and ”C" using the initializers defined above. 




1 ; 



main ( ) 

{ 

SOM_TraceLevel = 

A *a = new A; 
a->somPrintSelf () ; 
delete a; 
print f ( " \n" ) ; 

B *b = new B ( ) ; 
b->somPrintSelf () ; 
delete b; 
print f ( " \n" ) ; 

b = new B (22 ) ; 
b->somPrintSelf () ; 
delete b; 
print f ( " \n" ) ; 

C *c = new C; 
c->somPrintSelf () ; 
delete c; 
print f ( " \n" ) ; 

c = new C ( (Environment* ) 0 , 44); 
c->somPrintSelf () ; 
delete c; 
print f ( " \n" ) ; 

c = new C ( (Environment* ) 0 , "66"); 

c->somPrintSelf () ; 
delete c; 

} 



The output from the preceding program is as follows: 

"ctorFullExample . C" : 18: In A: somDef aultlnit 

"ctorFullExample . C" : 48: In A: somPrintSelf 

". /ctorFullExample . xih" : 292: In A:A_get_a 

{an instance of A at location 20063C38 with (a=l) } 



"ctorFullExample . C" : 


: 35: 


In 


A: somDestruct 


"ctorFullExample . C" : 


: 79: 


In 


B : somDef aultlnit 


"ctorFullExample . C" : 


: 110: 


In B : somPrintSelf 



". /ctorFullExample . xih" : 655: In B:B_get_b 

{an instance of B at location 20064578 with (b=2) } 
"ctorFullExample . C" : 97: In B : somDestruct 

"ctorFullExample . C" : 62: In B : BwithlnitialValue 

"ctorFullExample . C" : 110: In B : somPrintSelf 
". /ctorFullExample . xih" : 655: In B:B_get_b 

{an instance of B at location 20064578 with (b=22) } 
"ctorFullExample . C" : 97: In B : somDestruct 

"ctorFullExample . C" : 150: In C : somDef aultlnit 
"ctorFullExample . C" : 18: In A: somDef aultlnit 

"ctorFullExample . C" : 79: In B : somDef aultlnit 

"ctorFullExample . C" : 182: In C : somPrintSelf 
". /ctorFullExample . xih" : 292: In A:A_get_a 

". /ctorFullExample . xih" : 655: In B:B_get_b 

". /ctorFullExample . xih" : 1104: In C:C_get_c 

{an instance of C at location 20065448 with (a=l, b=2, c=3) } 
"ctorFullExample . C" : 169: In C : somDestruct 
"ctorFullExample . C" : 35: In A : somDestruct 

"ctorFullExample . C" : 97: In B : somDestruct 

"ctorFullExample . C" : 196: In C : CwithlnitialValue 

"ctorFullExample . C" : 18: In A: somDef aultlnit 

"ctorFullExample . C" : 62: In B : BwithlnitialValue 

"ctorFullExample . C" : 182: In C : somPrintSelf 

". /ctorFullExample . xih" : 292: In A:A_get_a 

". /ctorFullExample . xih" : 655: In B:B_get_b 

". /ctorFullExample . xih" : 1104: In C:C_get_c 

{an instance of C at location 20065448 with (a=l, b=33, c=44) } 

"ctorFullExample . C" : 169: In C : somDestruct 

"ctorFullExample . C" : 35: In A : somDestruct 

"ctorFullExample . C" : 97: In B : somDestruct 




"ctorFullExample . C" : 132: In C : CwithlnitialString 

"ctorFullExample . C" : 18: In A: somDef ault Init 

"ctorFullExample . C" : 62: In B : BwithlnitialValue 

"ctorFullExample . C" : 182: In C : somPrintSelf 

". /ctorFullExample . xih" : 292: In A:A_get_a 

". /ctorFullExample . xih" : 655: In B:B_get_b 

". /ctorFullExample . xih" : 1104: In C:C_get_c 

{an instance of C at location 20065448 with (a=l, b=55, c=66) } 

"ctorFullExample . C" : 169: In C : somDestruct 

"ctorFullExample . C" : 35: In A: somDestruct 

"ctorFullExample . C" : 97: In B : somDestruct 



Customizing the initialization of class objects 



As described previously, the somDefaultlnit method can be overridden to customize the initialization of objects. Because classes are 
objects, somDefaultlnit is also invoked on classes when they are first created (generally by invoking the somNew method on a metaclass). 
For a class object, however, somDefaultlnit normally just sets the name of the class to "unknown," after which the somlnitMICIass method 
must be used for the major portion of class initialization. Of course, metaclasses can override somDefaultlnit to initialize introduced class 
variables that require no arguments for their initialization. 

Note: Because somNew does not call somlnitMICIass, class objects returned from invocations of somNew on a metaclass are not yet 
useful class objects. 

The somlnitMICIass method (introduced by SOMCIass) is invoked on a new class object using arguments to indicate the class name and 
the parent classes from which inheritance is desired (among other arguments). This invocation is made by whatever routine is used to 
initialize the class. (For SOM classes using the C or C++ implementation bindings, this is handled by the somBuildClass procedure, which 
is called by the implementation bindings automatically.) The somlnitMICIass method is often overridden by a metaclass to influence 
initialization of new classes in some way. Typically, the overriding procedure begins by making parent method calls, and then performs 
additional actions thereafter. 

Flowever, without use of the Cooperative Metaclass to guarantee correct operation of SOMobjects in general, none of the methods 
introduced by SOMCIass should be overridden. As a result, customizing the initialization of class objects (other than through overriding 
somDefaultlnit for initialization of class variables) is not recommended in SOMobjects 2.1 . Users whose applications require this should 
request access to the experimental Cooperative Metaclass used to implement the SOMobjects Metaclass Framework. But, metaclasses 
implemented using the experimental Cooperative Metaclass may require reprogramming when SOMobjects introduces an officially 
supported Cooperative Metaclass. 



Creating a SOM Class Library 

One of the principal advantages of SOM is that it makes "black box" (or binary) reusability possible. Consequently, SOM classes are 
frequently packaged and distributed as class libraries. A class library holds the actual implementation of one or more classes and can be 
dynamically loaded and unloaded as needed bv applications. Importantly, class libraries can also be replaced independently of the 
applications that use them and, provided that the class implementor observes simple SOM guidelines for preserving binary compatibility, can 
evolve and expand over time. 



General guidelines for class library designers 



One of the most important features of SOM is that it allows you to build and distribute class libraries in binary form. Because there is no 
"fragile base class" problem in SOM, client programs that use your libraries (by subclassing your classes or by invoking the methods in your 
classes) will not need to be recompiled if you later produce a subsequent version of the library, provided you adhere to some simple 
restrictions. 



1 . 



You should always maintain the syntax and the semantics of your existing interfaces. This means that you cannot take away any 




exposed capabilities, nor add or remove arguments for any of your public methods. 



2. Always maintain the releaseorder list, so that it never changes except for additions to the end. The releaseorder should contain 
all of your public methods, the one or two methods that correspond to each public attribute, and a placeholder for each private 
method (or private attribute method). 

3. Assign a higher minorversion number for each subsequent release of a class, so that client programmers can determine 
whether a new feature is present or not. Change the majorversion number only when you deliberately wish to break binary 
compatibility. (See the topic "Modifier statements” in Chapter 4, "SOM IDL and the SOM Compiler" for explanations of the 

releaseorder, minorversion and majorversion modifiers.) 

4. Under Windows, you should avoid the use of methods or attributes that return structures. In the DOS/Windows environment, 
there is no universally agreed upon calling convention for returning structures that is observed by all popular language compilers. 
Instead, define attributes that return pointers to structures, or define methods that take an out parameter for passing a structure 
back to the caller. 

Note that you can always avoid this problem in classes of your own design. However, some of the attributes and methods in the 
frameworks that come with the SOMobjects Toolkit do return structures. Many of these are dictated by the OMG CORBA 
standard, and could not be avoided. For each of these methods two common calling conventions have been implemented: 

• Microsoft convention, where the address of the structure is returned in AX:DX, and 

• Borland convention, where the caller provides a hidden first argument to receive a copy of the returned structure. 

No action is needed on your part to use the Microsoft convention. To use the Borland convention, you should include the file 
BCCSTRUC.H following any other "includes" of SOM headers. 

5. With each new release of your class library, you have significant degrees of freedom to change much of the implementation 
detail. You can add to or reorganize your instance variables, add new public or private methods, inject new base classes into 
your class hierarchies, change metaclasses to more derived ones, and relocate the implementation of methods upward in your 
class hierarchies. Provided you always retain the same capabilities and semantics that were present in your first release, none of 
these changes will break the client programs that use your libraries. 



Types of class libraries 



Since class libraries are not programs, users cannot execute them directly. To enable users to make direct use of your classes, you must 
also provide one or more programs that create the classes and objects that the user will need. This section describes how to package your 
classes in a SOM class library and what you must do to make the contents of the library accessible to other programs. 

On AIX, class libraries are actually produced as AIX shared libraries, whereas on OS/2 or Windows they appear as dynamically-linked 
libraries (or DLLs). The term "DLL" is sometimes used to refer to either an AIX, an OS/2, or a Windows class library, and (by convention 
only) the file suffix ".dll" is used for SOM class libraries on all platforms. 

A program can use a class library containing a given class or classes in one of two ways: 

1 . If the programmer employs the SOM bindings to instantiate the class and invoke its methods, the resulting client program 
contains static references to the class. The operating system will automatically resolve those references when the program is 
loaded, by also loading the appropriate class library. 

2. If the programmer uses only the dynamic SOM mechanisms for finding the class and invoking its methods (for example, by 
invoking somFindClass, somFindMethod, somLookupMethod, somDispatch, somResolveByName,and so forth), the 
resulting client program does not contain any static references to the class library. Thus, SOM will load the class library 
dynamically during execution of the program. Note: For SOM to be able to load the class library, the dllname modifier must be 
set in the .idl file. (See the topic "Modifier statements" in Chapter 4, "SOM IDL and the SOM Compiler.") 

Because the provider of a class library cannot predict which of these ways a class will be used, SOM class libraries must be built such that 
either usage is possible. The first case above requires the class library to export the entry points needed by the SOM bindings, whereas 
the second case requires the library to provide an initialization function to create the classes it contains. The following topics discuss 
each case. 



Building export files 




The SOM Compiler provides an "exp" emitter for AIX and a ”def" emitter for OS/2 to produce the necessary exported symbols for each 
class. For example, to generate the necessary exports for a class "A", issue the sc or some command with one of the following -s options. 
(For a discussion of the sc or some command and options, see "Running the SOM Compiler" in Chapter 4, "SOM IDL and the SOM 
Compiler.”) 

For AIX, this command generates an "a. exp" file: 

sc -sexp a.idl 



For OS/2, this command generates an "a.def" file: 

sc -sdef a.idl 



Typically, a class library contains multiple classes. To produce an appropriate export file for each class that the library will contain, you can 
create a new export file for the library itself by combining the exports from each "exp" or "def" file into a single file. Following are examples of 
a combined export "exp" file for AIX and a combined "def" file for OS/2. Each example illustrates a class library composed of three classes, 
"A", "B", and "C". 

AIX "exp" file: 

#! abc.dll 

ACClassData 

AClassData 

ANewClass 

BCClassData 

BClassData 

BNewClass 

CCClassData 

CClassData 

CNewClass 



OS/2 "def" file: 

LIBRARY abc INI T INSTANCE 

DESCRIPTION 'abc example class library' 

PROTMODE 

DATA MULTIPLE NONSHARED LOADONCALL 
EXPORTS 

ACClassData 

AClassData 

ANewClass 

BCClassData 

BClassData 

BNewClass 

CCClassData 

CClassData 

CNewClass 



Other symbols in addition to those generated by the "def" or "exp" emitter can be included if needed, but this is not required by SOM. One 
feature of SOM is that a class library needs no more than three exports per class (by contrast, many OOP systems require externals for 
every method as well). One required export is the name of a procedure to create the class ( <ciassAiame>UewC\BLSS ), and the others are 
two external data structures that are referenced by the SOM bindings. 



Specifying the initialization function 



An initialization function for the class library must be provided to support dynamic loading of the library by the SOM Class Manager. The 
SOM Class Manager expects that, whenever it loads a class library, the initialization function will create and register class objects for all of 
the classes contained in the library. 

These classes are then managed as a group (called an affinity group). One class in the affinity group has a privileged position-namely, the 
class that was specifically requested when the library was loaded. If that class (that is, the class that caused loading to occur) is 
subsequently unregistered, the SOM Class Manager will automatically unregister all of the other classes in the affinity group as well, and will 
unload the class library. Similarly, if the SOM Class Manager is explicitly asked to unload the class library, it will also automatically 
unregister and free all of the classes in the affinity group. 




It is the responsibility of the class-library creator to supply the initialization function. The interface to the initialization function is given by the 
following C/C++ prototype: 

#ifdef I BMC 

#pragma linkage (SOMInitModule, system) 

#endif 

SOMEXTERN void SOMLINK SOMInitModule ( long maj orVersion, 

long minorVersion, 
string className) ; 



The parameters provided to this function are the c/assName and the major/minor version numbers of the class that was requested when the 
library was loaded (that is, the class that caused loading). The initialization function is free to use or to disregard this information; 
nevertheless, if it fails to create a class object with the required name, the SOM Class Manager considers the load to have failed. As a rule 
of thumb, however, if the initialization function invokes a <c/ass/\Zame> NewClass procedure for each class in the class library, this condition 
will always be met. Consequently, the parameters supplied to the initialization function are not needed in most cases. 

Here is a typical class-library initialization function, written in C, for a library with three classes ("A", "B", and "C"): 

#include "a.h" 

#include "b.h" 

#include "c.h" 

#ifdef I BMC 

#pragma linkage (SOMInitModule, system) 

#endif 



SOMEXTERN void 
{ 



SOMLINK SOMInitModule (long ma jorVersion, 

long minorVersion, string className) 



SOM_IgnoreWarning (ma jorVersion) ; /* This function makes */ 

SOM_IgnoreWarning (minorVersion) ; /* no use of the passed */ 

SOM_IgnoreWarning (className); /* arguments. */ 

ANewClass (A_Ma jorVersion, A_MinorVersion) ; 

BNewClass (B_Ma jorVersion, B_MinorVersion) ; 

CNewClass (C_Ma jorVersion, C_MinorVersion) ; 



The source code for the initialization function can be added to one of the implementation files for the classes in the library, or you can put it 
in a separate file and compile it independently. 



Using Windows class libraries 



Some additional considerations apply for Windows class libraries: Each class library must also supply a Windows LibMain function. The 
LibMain function is invoked automatically whenever a Windows DLL is loaded, and is responsible for identifying the library and its 
SOMInitModule function to the SOM Kernel. Here is an example of a typical Windows LibMain function for a SOM class library as it would 
appear in a C or C++ program: 

♦include <som.h> 

SOMEXTERN void SOMLINK SOMInitModule (long ma jorVersion, 

long minorVersion, 
string className) ; 



#include <windows.h> 

int CALLBACK LibMain (HINSTANCE inst, 

WORD ds, 

WORD Heapsize, 

LPSTR cmdLine) 

{ 

SOM_IgnoreWarning (inst) ; 

SOM_ignoreWarning (ds) ; 

SOM_IgnoreWarning (heapSize) ; 
SOM_IgnoreWarning (cmdLine) ; 

SOM_ClassLibrary ("xyz.dll"); 

return 1; /* Indicate success to loader */ 




The only operative statement in the LibMain function is the macro SOM_ClassLibrary, which identifies the actual file name of the library as 
it would appear in a Windows LoadLibrary call, and internally generates a reference to the library's SOMInitModule function. This 
information is passed to the SOM Kernel, which in turn registers the library and schedules the execution of the SOMInitModule function. 

Typically, the SOM Kernel invokes the SOMInitModule function of each statically loaded class library during execution of the 
SOM_MainProgram macro within the using application; otherwise, SOMInitModule is invoked immediately upon completio of the dynamic 
loading of a class library by an already executing application. Regardless of the loading mechanism, the SOM Kernel guarantees that the 
SOMInitModule function executes exactly once for each class library. 



Creating the import library 



Finally, for each of your class libraries, you should create an import library that can be used by client programs (or by other class libraries 
that use your classes) to resolve the references to your classes. 

Flere is an example illustrating all of the steps required to create a class library ("abc.dN”) that contains the three classes "A", "B", and "C". 



1 . Compile all of the implementation files for the classes that will be included in the library. Include the initialization function also. 
For AIX written in C: 



xlc -I. -I$SOMBASE/ include 
xlc -I. -I$SOMBASE/ include 
xlc -I, -I$SOMBASE/ include 
xlc -I. -I$SOMBASE/ include 



-c a . c 
-c b . c 
-c c . c 

-c initfunc.c 



For AIX written in C++: 



xlc -I. -I$SOMBASE/ include 
xlc -I. -I$SOMBASE/ include 
xlc -I. -I$SOMBASE/ include 
xlc -I. -I$SOMBASE/ include 



-c a . C 
-c b.C 
-c c . C 

-c initfunc.C 



For OS/2 written in C: 



icc 


-I . 


-I%SOMBASE%\include 


-Ge- 


-c 


a . c 


icc 


-I . 


-I%SOMBASE%\include 


-Ge- 


-c 


b . c 


icc 


-I . 


-I%SOMBASE%\include 


-Ge- 


-c 


c . c 


icc 


-I . 


-I%SOMBASE%\include 


-Ge- 


-c 


init f unc . c 



Note: The "-GE" option is used only with the IBM compiler. It indicates that the object files will go into a DLL. 
For OS/2 written in C++: 



icc 


-I . 


-I%SOMBASE%\include 


-Ge- 


-c 


a . cpp 


icc 


-I . 


-I%SOMBASE%\include 


-Ge- 


-c 


b . cpp 


icc 


-I . 


-I%SOMBASE%\include 


-Ge- 


-c 


c . cpp 


icc 


-I . 


-I%SOMBASE%\include 


-Ge- 


-c 


init f unc . cpp 



Note: The "-Ge" option is used only with the IBM compiler. It indicates that the object files will go into a DLL. 
2. Produce an export file for each class. 

For AIX: 

sc -sexp a.idl b.idl c.idl 



For OS/2: 



sc -sdef a.idl b.idl c.idl 




3. 



Manually combine the exported symbols into a single file. 



For AIX, create a file "abc.exp" from "a. exp", "b.exp", and "c.exp". Do not include the initialization function (SOMInitModule) in 
the export list. 

For OS/2, create a file "abc.def" from "a.def, "b.def", and c.def". Include the initialization function (SOMInitModule) in the export 
list, so that all classes will be initialized automatically, unless your initialization function does not need arguments and you 
explicitly invoke it yourself from an OS/2 DLL initialization routine. 

4. Using the object files and the export file, produce a binary class library. 

For AIX: 

Id -o abc.dll -bE: abc.exp -e SOMInitModule -H512 -T512 \ 
a.o b.o c.o initfunc.o -lc -L$SOMBASE/lib -lsomtk 



The -o option assigns a name to the class library ("abc.dll"). The -bE: option designates the file with the appropriate export list. 
The -e option designates SOMInitModule as the initialization function. The -H and -T options must be supplied as shown; they 
specify the necessary alignment information for the text and data portions of your code. The -I options name the specific libraries 
needed by your classes. If your classes make use of classes in other class libraries, include a -I option for each of these also. 
The Id command looks for a library named "lib<ur>.a", where <x> is the name provided with each -I option. The -L option 
specifies the directory where the "somtk" library resides. 

For OS/2: 

set LIB=%SOMBASE%\lib; %LIB% 

link386 / noi /packd /packc /align: 16 /exepack \ 

a.obj b.obj c.obj initfunc . ob j , abc . dll, , os2386 somtk, \ 
abc . def 



If your classes make use of classes in other class libraries, include the names of their import libraries immediately after "somtk" 
(before the next comma). 

5. Create an import library that corresponds to the class library, so that programs and other class libraries can use (import) your 
classes. 



For AIX: 

ar ruv libabc.a abc.exp 'Note the use of the ".exp" file, not a ".o" file 



The first filename ("libabc.a") specifies the name to give to the import library. It should be of the form "libor>.a", where <x> represents your 
class library. The second filename ("abc.exp") specifies the exported symbols to include in the import library. 

Caution: Although AIX shared libraries can be placed directly into an archive file ("lib<jr>.a"), this is not recommended! A SOM class library 
should have a corresponding import library constructed directly from the combined export file. 

For OS/2: 

implib /noi abc. lib abc.def 



The first filename ("abc. lib") specifies the name for the import library and should always have a suffix of ".lib". The second filename 
("abc.def") specifies the exported symbols to include in the import library. 

Note: SOMInitModule should be included in the <x>.dll but not in <x>.lib. If you are using an export file that contains the symbol 
SOMInitModule, delete it first; SOMInitModule should not appear in your import library because it need not be exported. 
SOMInitModule should be included when creating your file <x>.dll because all classes in the <x>.dll will be initialized. 



Customizing Memory Management 



SOM is designed to be policy free and highly adaptable. Most of the SOM behavior can be customized by subclassing the built-in classes 
and overriding their methods, or by replacing selected functions in the SOM run-time library with application code. This chapter contains 
more advanced topics describing how to customize the following aspects of SOM behavior: memory management, dynamic class loading 




and unloading, character output, error handling, and method resolution. Information on customizing Distributed SOM is provided in Chapter 
6 . 

The memory management functions used by the SOM run-time environment are a subset of those supplied in the ANSI C standard library. 
They have the same calling interface and return the equivalent types of results as their ANSI C counterparts, but include some supplemental 
error checking. Errors detected in these functions result in the invocation of the error-handling function to which SOMError points. 

The correspondence between the SOM memory-management function variables and their ANSI standard library equivalents is given in the 
table below. 



Memory-Management Functions 



SOM FUNCTION 
VARIABLE 


ANSI STANDARD 

LIBRARY 

FUNCTION 


C RETURN TYPE 


ARGUMENT TYPES 


SOMCalloc 


calloc ( ) 


somToken 


size_t, size_t 


SOMFree 


free ( ) 


void 


somToken 


SOMMalloc 


malloc ( ) 


somToken 


size_t 


SOMRealloc 


realloc ( ) 


somToken 


somToken, size. 



An application program can replace SOM's memory management functions with its own memory management functions to change the way 
SOM allocates memory (for example, to perform all memory allocations as suballocations in a shared memory heap). This replacement is 
possible because SOMCalloc, SOMMalloc, SOMRealloc, and SOMFree are actually g/oba/ var/ab/es that point to SOM's default memory 
management functions, rather than being the names of the functions themselves. Thus, an application program can replace SOM's default 
memory management functions by assigning the entry-point address of the user-defined memory management function to the appropriate 
global variable. For example, to replace the default free procedure with the user-defined function MyFree (which must have the same 
signature as the ANSI C free function), an application program would require the following code: 



#include <som.h> 

/* Define a replacement routine: */ 



#ifdef 


OS 2. 


/* 


not 


for 


SOM 


3.0 


*/ 


♦pragma 


linkage (myFree, 


system) /* 


not 


for 


SOM 


3.0 


*/ 


#endif 




/* 


not 


for 


SOM 


3.0 


*/ 



void SOMLINK myFree (somToken memPtr) 
{ 

(Customized code goes here) 

} 

SOMFree = myFree; 



Note: In general, all of these routines should be replaced as a group. For instance, if an application supplies a customized version of 

SOMMalloc, it should also supply correponding SOMCalloc, SOMFree, and SOMRealloc functions that conform to this same style of 
memory management. 



Customizing Class Loading and Unloading 



SOM uses three routines that manage the loading and unloading of class libraries (referred to here as DLLs). These routines are called by 
the SOMCIassMgrObject as it dynamically loads and registers classes. If appropriate, the rules that govern the loading and unloading of 
DLLs can be modified, by replacing these functions with alternative implementations. 



Customizing class initialization 




The SOMCIassInitFuncName function has the following signature: 

string (*SOMCIasslnitFuncName) ( ); 

This function returns the name of the function that will initialize (create class objects for) all of the classes that are packaged together in a 
single class library. (This function name applies to all class libraries loaded by the SOMCIassMgrObject.) The SOM-supplied version of 
SOMCIassInitFuncName returns the string " SOMInitModule'. The interface to the library initialization function is described under the topic 
"Creating a SOM Class Library" earlier in this chapter. 



Customizing DLL loading 



To dynamically load a SOM class, the SOMCIassMgrObject calls the function pointed to by the global variable SOMLoadModule to load 
the DLL containing the class. The reason for making public the SOMLoadModule function (and the following SOMDeleteModule function) 
is to reveal the boundary where SOM touches the operating system. Explicit invocation of these functions is never required. However, they 
are provided to allow class implementors to insert their own code between the operating system and SOM, if desired. The 
SOMLoadModule function has the following signature: 

long ('SOMLoadModule) ( string c/ass/Vame, 

string f/ZeName, 

string functZonName , 

long ma/orVersZon , 

long mZnordersZon , 

somToken * modHandZe\, 

This function is responsible for loading the DLL containing the SOM class c/assName and returning either the value zero (for success) or a 
nonzero system-specific error code. The output argument modHand/e is used to return a token that can subsequently be used by the 
DLL-un loading routine (described below) to unload the DLL. The default DLL-loading routine returns the DLL's modu/e hand/e in this 
argument. The remaining arguments are used as follows: 



Argument 

fZ/eName 



functZonName 



ma/orVersZon 



Usage 

The file name of the DLL to be loaded, which can be either a simple name or a full 
path name. 

The name of the routine to be called after the DLL is successfully loaded by the 
SOMCIassMgrObject. This routine is responsible for creating the class objects for 
the class(es) contained in the DLL. Typically, this argument has the value 
"SOMInitModule", which is obtained from the function SOMCIassInitFuncName 
described above. If no SOMInitModule entry exists in the DLL, the default 
DLL-loading routine looks in the DLL for a procedure with the name 
<c/assName> NewClass instead. If neither entry point can be found, the default 
DLL-loading routine fails. 

The major version number to be passed to the class initialization function in the 
DLL (specified by the functZonName argument). 



mZnorVersZon 



The minor version number to be passed to the class initialization function in the 
DLL (specified by the FunctZonZVame argument). 



An application program can replace the default DLL-loading routine by assigning the entry point address of the new DLL-loading function 
(such as MyLoadModu/e ) to the global variable SOMLoadModule, as follows: 



ftinclude <som.h> 

/* Define a replacement routine: */ 

long myLoadModule (string className, string fileName, 

string functionName, long ma jorVersion, 
long minorVersion, somToken *modHandle) 

{ 

(Customized code goes here) 

} 



SOMLoadModule = MyLoadModule; 




Customizing DLL unloading 



To unload a SOM class, the SOMCIassMgrObject calls the function pointed to by the global variable SOMDeleteModule. The 
SOMDeleteModule function has the following signature: 

long ('SOMDeleteModule) (in somToken modHand/e\, 

This function is responsible for unloading the DLL designated by the modHand/e parameter and returning either zero (for success) or a 
nonzero system-specific error code. The parameter modHand/e contains the value returned by the DLL loading routine (described above) 
when the DLL was loaded. 

An application program can replace the default DLL-unloading routine by assigning the entry point address of the new DLL-unloading 
function (such as, MyDe/eteModu/e) to the global variable SOMDeleteModule, as follows: 

ftinclude <som.h> 

/* Define a replacement routine: */ 
long myDeleteModule (somToken modHandle) 

{ 

(Customized code goes here) 

} 

SOMDeleteModule = MyDeleteModule; 



Customizing Character Output 



The SOM character-output function is invoked by all of the SOM error-handling and debugging macros whenever a character must be 
generated (see "Debugging" and "Exceptions and error handling" in Using SOM Classes in Client Programs, "Using SOM Classes in Client 
Programs"). The default character-output routine, pointed to by the global variable SOMOutCharRoutine, simply writes the character to 
"stdout”, then returns 1 if successful, or 0 otherwise. 

For convenience, SOMOutCharRoutine is supplemented by the somSetOutChar function. The somSetOutChar function enables each 
task to have a customized character output routine, thus it is often preferred for changing the output routine called by somPrintf (because 
SOMOutChrRoutine would remain in effect for subsequent tasks). On Windows, the somSetOutChar function is required (rather than 
SOMOutCharRoutine): it is optional on other operating systems. 

An application programmer might wish to supply a customized replacement routine to: 

• Direct the output to stderr, 

• Record the output in a log file, 

• Collect characters and handle them in larger chunks, 

• Send the output to a window to display it, 

• Place the output in a clipboard, or 

■ Some combination of these. 

With SOMOutCharRoutine, an application program would use code similar to the following to install the replacement routine: 

ftinclude <som.h> 

♦pragma linkage (myCharacterOutputRoutine, system) 

/* Define a replacement routine: */ 

int SOMLINK myCharacterOutputRoutine (char c) 

{ 

(Customized code goes here) 



/* After the next stmt all output */ 

/* will be sent to the new routine */ 
SOMOutCharRoutine = myCharacterOutputRoutine; 



With somSetOutChar, an application program would use code similar to the following to install the replacement routine: 

#include <som.h> 

static int irOutChar (char c) ; 

static int irOutChar (char c) 

{ 

(Customized code goes here) 

} 



main (...) 

{ 

somSetOutChar ( (somTD_SOMOutCharRoutine *) irOutChar); 
} 



Customizing Error Handling 



When an error occurs within any of the SOM-supplied methods or functions, an error-handling procedure is invoked. The default 
error-handling procedure supplied by SOM, pointed to by the global variable SOMError, has the following signature: 

void (*SOMError) (int errorCode , string fi/eName, int /ineNum ); 

The default error-handling procedure inspects the errorCode argument and takes appropriate action, depending on the last decimal digit of 
errorCode (see "Exceptions and error handling" in Using SOM Classes in Client Programs for a discussion of error classifications). In the 
default error handler, fatal errors terminate the current process. The remaining two arguments ( fi/eName and /ineNum), which indicate the 
name of the file and the line number within the file where the error occurred, are used to produce an error message. 

An application programmer might wish to replace the default error handler with a customized error-handling routine to: 

• Record errors in a way appropriate to the particular application, 

• Inform the user through the application's user interface, 

• Attempt application-level recovery by restarting at a known point, or 

• Shut down the application. 

An application program would use code similar to the following to install the replacement routine: 

((include <som.h> 

/* Define a replacement routine: */ 

void myErrorHandler (int errorCode, string fileName, int lineNum) 

{ 

(Customized code goes here) 

} 

/* After the next stmt all errors */ 

/* will be handled by the new routine */ 

SOMError = myErrorHandler; 



When any error condition originates within the classes supplied with SOM, SOM is left in an internally consistent state. If appropriate, an 
application program can trap errors with a customized error-handling procedure and then resume with other processing. Application 
programmers should be aware, however, that all methods within the SOM run-time library behave atomica//y. That is, they either succeed or 
fail; but if they fail, partial effects are undone wherever possible. This is done so that all SOM methods remain usable and can be 
re-executed following an error. 



Customizing Mutual Exclusion Services (Thread Safety) 



The SOM kernel and the other SOMobjects frameworks (DSOM, Persistence, Replication, and so on), have been made thread safe with 
respect to multi-threaded processes. As used here, "thread safe" means that the SOMobjects run time has been implemented using mutua/ 
exc/us/on semaphores to protect sections of the code which must only be executed by a single thread in a multi-threaded application 
process at one time. 

Some operating systems provide native multi-threading (for example, OS/2.) On other operating systems that do not support native 
multi-threading (such as, AIX 3.2), thread support may be provided as part of particular programming environments (like DCE) or libraries. 

It is vital that SOM employ the mutex services that are provided by the thread package used by the application. Consequently, SOM 
provides a mechanism for defining and customizing mutex services. 

Five mutex service functions are used to implement mutual exclusion in SOM. These functions are called indirectly via the global pointer 
variables defined below. A somToken parameter (called "sem” below) is used as a generic "handle to refer to a mutex semaphore - usually 
it is a pointer to a mutex semaphore variable or data structure. The actual representation of the mutex semaphore is hidden by the functions. 

unsigned long (*SOMCreateMutexSem) (somToken *sem) ; 



The referenced function creates a mutex semaphore, whose handle is returned as an output parameter in the somToken 

variable identified by 

"sem". 

If the call succeeds, a 0 is returned. Otherwise, a non-zero error code is returned. 



unsigned long (*SOMRequestMutexSem) (somToken sem) ; 



The referenced function requests ownership of the mutex semaphore identified by the parameter, sem. If the semaphore is not 
currently owned by another thread, ownership is assigned to the calling thread. Otherwise, the calling thread is blocked until the 
semaphore is released by the current owner. 

/mportant.' If the same thread calls SOMRequestMutexSem multiple times, a reference count must be kept, so that the 
semaphore is released only after the same number of calls to SOMReleaseMutexSem. Some, but not all, thread packages 
provide reference counting automatically, via "counting semaphores." 

If the call succeeds, a 0 is returned. Otherwise, a non-zero error code is returned. 



unsigned long (*SOMReleaseMutexSem) (somToken sem) ; 



The referenced function releases ownership of the mutex semaphore identified by the parameter, sem. 



/mportanh If the same thread calls SOMRequestMutexSem multiple times, a reference count must be kept, so that the 
semaphore is released only after the same number of calls to SOMReleaseMutexSem. Some, but not all, thread packages 
provide reference counting automatically, via "counting semaphores." 

If the call succeeds, a 0 is returned. Otherwise, a non-zero error code is returned. 



unsigned long (*SOMDestroyMutexSem) (somToken sem) ; 



The referenced function destroys the a mutex semaphore identified by the parameter, sem. 
If the call succeeds, a 0 is returned. Otherwise, a non-zero error code is returned. 



unsigned long (*SOMGetThreadId) (); 



The referenced function returns a small integer identifier for the calling thread. The ID cannot be associated with any other 
thread in the process. The ID is used as an index for table lookups. 

If threads are not supported, the function must return 0. 

The actual mutex service function prototypes and global variable declarations are found in file "somapi.h". 

If the underlying operating system supports native multi-threading (currently, only OS/2), SOM provides appropriate default mutex service 




function implementations. On those operating systems that do not support native multi-threading, the default mutex service functions have 
null implementations. 

An application may want to use threading services different from those provided by the underlying operating system (if any); for example, 
DCE applications will want to use DCE threads. In that case, the default mutex service functions can be replaced by application-defined 
functions. 

An application program would use code similar to the following to install the replacement routines: 

((include <som.h> 

/* Define a replacement routine: */ 
unsigned long myCreateMutexSem (somToken *sem) 

{ 

(Customized code goes here) 

? 



SOMCreateMutexSem^ myCreateMutexSem; 



It is important to install custom mutex service functions before any SOM calls are made. 



Customizing Multi -threading Services 



Although the SOM kernel and the other SOMobjects frameworks allow applications to be multi-threaded, the kernel and frameworks 
generally do not require or exploit threads themselves. But there are some exceptions: for example, application servers in DSOM can be 
configured so that each incoming request is executed on a separate thread. 

An application may choose to employ "native" multi-threading services provided by the underlying operating system (for example, OS/2). On 
other operating systems that do not support native multi-threading (such as, AIX 3.2), thread support may be provided as part of particular 
programming environments (like DCE) or libraries. SOM provides a mechanism that allows an application to define and customize the 
multi-threading services used by SOMobjects frameworks. 

Four thread service functions are defined for use by SOMobjects frameworks. These functions may be called indirectly via the global pointer 
variables defined below. A somToken parameter (called "thrd" below) is used as a generic "handle" to refer to a thread # usually it is a 
pointer to a thread id or descriptor. The actual representation of the thread handle is hidden by the functions. 

typedef void somTD_SOMThreadProc (void * data); 

unsigned long (*SOMStart Thread) (somToken *thrd, 

somTD_SOMThreadProc proc, 
void *data, 
unsigned long datasz, 
unsigned long stacksz) ; 



The referenced function starts a thread, and returns a thread handle in the somToken variable identified by "thrd". The thread 
executes the procedure whose address is specified by the proc parameter; the thread procedure takes a single void* argument 
and returns void. The data parameter passed to SOMStartThread is passed on to the thread procedure; the size of the data 
parameter, in bytes, is given by datasz. A stack of stacksz bytes will be allocated for the thread. 

Note: On OS/2, the thread procedure must be compiled with _Optlink linkage.) 

If the call succeeds, a 0 is returned. Otherwise, a non-zero error code is returned. 



unsigned long (*SOMEndThread) (void) ; 



The referenced function terminates the calling thread. 

If the call succeeds, a 0 is returned. Otherwise, a non-zero error code is returned. 



unsigned long (*SOMKillThread) (somToken thrd) ; 



The referenced function terminates the thread identified by the input parameter thrd. 




If the call succeeds, a 0 is returned. Otherwise, a non-zero error code is returned. 



unsigned long (*SOMGetThreadHandle) (somToken * thrd) ; 



The referenced function returns a handle that can be used to identify the calling thread. The handle is returned in the somToken 
variable pointed to by thrd. 

If the call succeeds, a 0 is returned. Otherwise, a non-zero error code is returned. 

The actual mutex service function prototypes and global variable declarations are found in file "somthrd.h". 

If the underlying operating system supports native multi-threading (currently, only OS/2), SOM provides appropriate default multi-threading 
service function implementations. On those operating systems that do not support native multi-threading, the default multi-threading service 
functions have null implementations. 

An application may want to use threading services different from those provided by the underlying operating system (if any); for example, 
DCE applications will want to use DCE threads. In that case, the default multi-threading service functions can be replaced by 
application#defined functions. 

An application program would use code similar to the following to install the replacement routines: 

#include <somthrd.h> 

/* Define a replacement routine: */ 
unsigned long myStartThread (somToken *thrd, 

somTD_SOMThreadProc proc, 
void *data, 
unsigned long datasz, 
unsigned long stacksz) 

{ 

(Customized code goes here) 

} 



SOMStartThread =myStartThread; 



It is important to install custom multi-threading service functions before any SOM calls are made. 



Distributed SOM (DSOM) 



Note: The SOMobject Base Toolkit provides the capability for implementing Workstation Distributed System Object Module (DSOM) 

(distribution among processes on a single machine). Implementing an application that is distributed across a network of machines 
requires Workgroup DSOM, which is available only in the full-capability SOMobjects Developer Toolkit. 



The following subjects are discussed in this section: 

• A Simple DSOM Example 

• Basic Client Programming 

• Basic Server Programming 

• Implementing Classes 

• Configuring DSOM Applications 

• Running DSOM Applications 

• DSOM as a CORBA-compliant Object Request Broker 

• Advanced Topics 

• Error Reporting and Troubleshooting 

• Limitations 



What is Distributed SOM? 



Whereas the power of SOM technology comes from the fact that SOM insulates the client of an object from the object's implementation, the 




power of DSOM lies in the fact that DSOM insulates the client of an object from the object's location. 



Distributed SOM (or DSOM) provides a framework that allows application programs to access objects across address spaces. That is, 
application programs can access objects in other processes, even on different machines. Both the location and implementation of an object 
are hidden from a client, and the client accesses the object (by way of method calls) in the same manner regardless of its location. 

DSOM currently supports two types of distribution: 

1 . distribution among processes on the same machine (referred to as Workstation DSOM) 

2. and distribution among a network of machines (referred to as Workgroup DSOM). 

DSOM runs on the AIX (Release 3.2.5 and above) and OS/2 (Release 2.0 and above) operating systems. A Workstation DSOM application 
can run on a machine in either environment using core capabilities of the SOMobjects system. Under the full capability SOMobjects 
Developer Toolkit, Workgroup DSOM supports distribution across local area networks comprised of both OS/2 and AIX systems. Future 
releases of DSOM may support large, enterprise-wide networks. 

Support for TCP/IP and NewWare IPX/SPX is provided on AIX, OS/2, and Windows. NetBIOS support is provided for OS/2 and Windows. 
DSOM communications is extensible in that an application can provide its own transport (see Appendix C of the SOMobjects Base Toolkit 
Users Guide). 

DSOM can be viewed in two ways: 

1 . As a System Object Model extension that allows a program to invoke methods on SOM objects in other processes. 

2. As an Object Request Broker (ORB); that is, a standardized "transport 1 ' for distributed object interaction. In this respect, DSOM 
complies with the Common Object Request Broker Architecture (CORBA) specification, published by the Object Management 
Group (OMG) and x/Open. 

This chapter describes DSOM from both perspectives. 



DSOM features 



Here is a quick summary of some of DSOM's more important features: 

• Uses the standard SOM Compiler, Interface Repository, language bindings, and class libraries. Thus, DSOM provides a growth 
path for non-distributed SOM applications. 

• Allows an application program to access a mix of local and remote objects. The fact that an object is remote is transparent to the 
program. 

• Provides run-time services for creating, destroying, identifying, locating, and dispatching methods on remote objects. These 
services can be overridden or augmented to suit the application. 

• Uses existing interprocess communication (IPC) facilities for Workstation communication, and common local area network (LAN) 
transport facilities for Workgroup communications. Support for TCP/IP, Netware IPX/SPX, and NetBios is provided. DSOM 
communications is extensible in that an application can provide its own transport. 

• Provides support for writing multi-threaded servers and event-driven programs. 

• Provides a default object server program, which can be easily used to create SOM objects and make those objects accessible to 
one or more client programs. If the default server program is used, SOM class libraries are loaded upon demand, so no server 
programming or compiling is necessary. 

• Complies with the CORBA 1 .1 specification, which is important for application portability. 



When to use DSOM 



DSOM should be used for those applications that require sharing of objects among multiple programs. The object actually exists in only one 
process (this process is known as the object's server); the other processes (known as clients) access the object through remote method 
invocations, made transparent by DSOM. 




DSOM should also be used for applications that require objects to be isolated from the main program. This is usually done in cases where 
reliability is a concern, either to protect the object from failures in other parts of the application, or to protect the application from an object. 

Some distributed applications may have special performance, reliability, or cooperative processing requirements, to which the SOM 
Replication framework is better suited. The Replication framework is oriented toward "groupware" (multi-party cooperative processing) 
applications, and has facilities for fault tolerance and recovery. The Replication framework is distinct from DSOM in that it maintains a 
complete replica of an object in each participant's address space, while DSOM establishes remote connections to shared objects. The 
Replication Framework is available only in the full-capability SOM objects Developer Toolkit. 



Chapter Outline 



Briefly, this section covers the following subjects: 

• Tutorial example 

• Programming DSOM applications 

• Configuring DSOM applications 

• Running DSOM applications 

• DSOM and CORBA 

• Advanced topics 

• Error reporting and troubleshooting 



Tutorial example 



First, a complete example shows how an existing SOM class implementation (a "stack") can be used with DSOM to create a distributed 
"Stack" application. Using the "Stack" example as a backdrop, the basic DSOM interfaces are introduced. 



Programming DSOM applications 



All DSOM applications involve three kinds of programming: 

• Client programming: writing code that uses objects; 

• Server programming: writing code that implements and manages objects. 

• Implementing classes: writing code that implements objects. 

Three sections ("Basic Client Programming", "Basic Server Programming", and Implementing Classes”) describe how to create DSOM 
applications from these three points of view. In turn, the structure and services of the relevant DSOM run-time environment are explained. 

Note: The three sections are presented in the order above to aid in their explanation. Plowever, the actual programming tasks are likely to 
be performed in the opposite order. 

Additional examples are provided in these sections to illustrate DSOM services. 



Configuring DSOM applications 



The section "Configuring DSOM Applications" explains what is necessary to set up a DSOM application, once the application has been built. 



Running DSOM applications 




The section "Running DSOM Applications" explains what is necessary to run a DSOM application, once it has been built and configured. 



DSOM and CORBA 

Those readers interested in using DSOM as a CORBA-compliant ORB should read the section entitled "DSOM as a CORBA compliant 
Object Broker." That section answers the question: How are CORBA concepts implemented in DSOM? 



Advanced topics 



The section on "Advanced Topics" covers the following: 

1 . "Peer versus client/server processes" demonstrates how peer-to-peer object interactions are supported in DSOM. 

2. "Dynamic Invocation Interface" details DSOM support for the CORBA dynamic invocation interface to dynamically build and 
invoke methods on remote objects. 

3. "Creating user-supplied proxy classes" describes how to override proxy generation by the DSOM run time and, instead, install a 
proxy object supplied by the user. 

4. "Customizing the default base proxy class"discusses how the SOMDClientProxy class can be subclassed to define a 
customized base class that DSOM will use during dynamic proxy-class generation. 

5. "Sockets class" describes how DSOM uses Sockets subclasses. 



Error reporting and troubleshooting 



The section on "Error Reporting and Troubleshooting” discusses facilities to aid in problem diagnosis. 



A Simple DSOM Example 



A sample "Stack" application is presented in this section as a tutorial introduction to DSOM. It demonstrates that, for simple examples like a 
"Stack", after very little work, the class can be used to implement distributed objects that are accessed remotely. The example first presents 
the "Stack" application components and the steps that the implementer must perform before the application can be run, and then describes 
the run time activity that results from executing the application. This run-time scenario introduces several of the key architectural 
components of the DSOM run-time environment. 

The source code for this example is provided with the DSOM samples in the SOMobjects Developer Toolkit. 



The "Stack" interface 



The example starts with the assumption that the class implementer has successfully built a SOM class library DLL, called "stack.dll”, in the 
manner described in Section 5.6, "Creating a SOM Class Library," of Chapter 5, "Implementing Classes in SOM." The DLL implements the 
following IDL interface. 




#include <somobj.idl> 



interface Stack: SOMObject 

{ 

const long stackSize = 10; 
exception STACK_OVERFLOW{ } ; 
exception STACK_UNDERFLOW{ } ; 
boolean full ( ) ; 
boolean empty (); 

long top() raises (STACK_UNDERFLOW) ; 
long pop() raises (STACK_UNDERFLOW) ; 

void push (in long element) raises (STACK_OVERFLOW) ; 

#ifdef SOMIDL 

implementation 

{ 

releaseorder : full, empty, top, pop, push; 
somDef aultlnit : override; 

long stackTop; // top of stack index 

long stackValues [stackSize] ; // stack elements 

dllname = "stack.dll"; 

}; 

#endif 

} ; 



This DLL could have been built without the knowledge that it would ever be accessed remotely (that is, built following the procedures in 
Chapter 5). Note, however, that some DLLs may require changes in the way their classes pass arguments and manage memory, in order to 
be used by remote clients (see the topic "Implementation Constraints" in section 6.5, "Implementing Classes"). 



The "Stack" class implementation 



#define Stack_Class_Source 
[(include <stack.ih> 

SOM_Scope boolean SOMLINK full (Stack somSelf , Environment *ev) 

{ 

StackData *somThis = StackGetData (somSelf ) ; 

StackMethodDebug ( "Stack" , "full" ) ; 

/* Return TRUE if stack is full. */ 
return (_stackTop == stackSize) ; 

} 



SOM_Scope boolean SOMLINK empty (Stack somSelf, Environment *ev) 

{ 

StackData *somThis = StackGetData (somSelf ) ; 

StackMethodDebug ( "Stack" , "empty") ; 

/* Return TRUE if stack is empty.*/ 
return (_stackTop == 0) ; 

} 

SOM_Scope long SOMLINK top (Stack somSelf, Environment *ev) 

{ 

StackData *somThis = StackGetData (somSelf ) ; 

StackMethodDebug ( "Stack" , "top") ; 

if (_stackTop > 0) 

{ 

/* Return top element in stack without removing it from 
* the stack. 

*/ 

return (_stackValues [_stackTop-l ] ) ; 




else 

{ 

somSetException (ev, USER_EXCEPTION, 

ex_STACK_UNDERFLOW, NULL) ; 

return (-1L) ; 

} 



SOM_Scope long SOMLINK pop (Stack somSelf, Environment *ev) 

{ 

StackData *somThis = StackGetData (somSelf ) ; 
StackMethodDebug ( "Stack" , "pop") ; 

if (_stackTop > 0) 

{ 

/* Return top element in stack and remove it from the 
* stack. 

*/ 

_stackTop — ; 

return (_stackValues [_stackTop] ) ; 

} 

else 

{ 

somSetException (ev, USER_EXCEPTION, 

ex_STACK_UNDERFLOW, NULL) ; 

return (-1L) ; 

} 

} 



SOM_Scope void SOMLINK push (Stack somSelf, 

Environment *ev, long el) 

{ 

StackData *somThis = StackGetData (somSelf ) ; 
StackMethodDebug ( "Stack" , "push") ; 

if (_stackTop < stackSize) 

{ 

/* Add element to top of the stack. */ 
_stackValues [_stackTop] = el; 

_stackTop++; 



else 

{ 



somSetException (ev, USER_EXCEPTION, 
e x_S T AC K_OVE RF L OW , 



NULL) ; 



SOM_Scope void SOMLINK somDefaultlnit (Stack somSelf, 

somlnitCtrl* Ctrl) 



StackData *somThis; 
somlnitCtrl globalCtrl; 
somBooleanVector myMask; 

StackMethodDebug ( "Stack" , "somDefaultlnit " ) ; 
Stack_BeginInitializer_somDef ault Init ; 



Stack_Init_SOMObject_somDefaultInit (somSelf , Ctrl) ; 

/* stackTop is index into stackValues for next pushed 

* stack element . 

* stackValues [ 0 .. (stackSize-1 ) ] holds stack elements. 
*/ 

_stackTop = 0; 



Client program using a local stack 



A simple client program written to use a local "Stack" object is displayed below. This C program is shown so that the differences between a 




local and remote client program can be highlighted. 

♦include <stack.h> 

boolean OperationOK (Environment *ev) ; 

int main(int argc, char *argv[]) 

{ 

Environment ev; 

Stack stk; 
long num = 100; 



SOM_InitEnvironment (&ev) ; 

/* The StackNewClass invocation is optional and unnecessary 

* in the client program when the class object is created in 

* the SOMInitModule function that is invoked during DLL 

* initialization. 

*/ 

StackNewClass (Stack_Ma jorVersion, Stack_MinorVersion) ; 
stk = StackNewO; 

/* Verify successful object creation */ 
if ( stk ! = NULL ) 

{ 

while ( !_full(stk, &ev) ) 

{ 

_push(stk, &ev, num); 

somPrintf ( "Top : %d\n", _top(stk, &ev) ) ; 
num += 100; 

} 



/* Test stack overflow exception */ 
_push(stk, &ev, num); 

OperationOK (&ev) ; 

while ( !_empty(stk, &ev) ) 

{ 

somPrintf ( "Pop : %d\n" , _pop(stk, &ev) ) ; 

} 



/* Test stack underflow exception */ 

somPrintf ( "Top Underflow: %d\n" , _top(stk, &ev) ) ; 

OperationOK (&ev) ; 

somPrintf ( "Pop Underflow: %d\n" , _pop(stk, &ev) ) ; 
OperationOK (&ev) ; 

_push(stk, &ev, -10000); 

somPrintf ( "Top : %d\n", _top(stk, &ev)); 

somPrintf ( "Pop : %d\n", _top(stk, &ev) ) ; 

_somFree (stk) ; 

} 



SOM_UninitEnvironment (&ev) ; 
return (0) ; 



boolean OperationOK (Environment *ev) 

{ 

char *exID; 

switch (ev->_major) 

{ 

case SYSTEM_EXCEPTION : 

exID = somExceptionld (ev) ; 

somPrintf ( "System exception: %s\n", exID) ; 
somdExceptionFree (ev) ; 
return (FALSE) ; 



case USER_EXCEPTION : 




exID = somExceptionld (ev) ; 

somPrintf ( "User exception: %s\n" , exID); 

somdExceptionFree (ev) ; 

return (FALSE) ; 

case NO_EXCEPTION : 
return (TRUE) ; 

default : 

somPrintf (" Invalid exception type in Environment . \n" ) ; 
somdExceptionFree (ev) ; 
return (FALSE) ; 




Client program using a remote stack 



The preceding program has been rewritten below showing how DSOM can be used to create and access a "Stack" object somewhere in the 
system. The exact location of the object does not matter to the application; it just wants a "Stack" object. Note that the stack operations of 
the two programs are identical. The main differences lie in stack creation and destruction, as highlighted below. (Also see "Memory 
management" later for more information on allocating and freeing memory.) 

ffinclude <somd.h> 

((include <stack.h> 

int main(int argc, char *argv] ) 

{ 

Environment ev; 

Stack stk; 
long num = 100; 

SOM_InitEnvironment (&ev) ; 

SOMD_Init (&ev) ; 



/* The StackNewClass invocation is optional and unnecessary 

* in the client program when the class object is created in 

* the SOMInitModule function that is invoked during DLL 

* initialization. 

*/ 

StackNewClass (Stack_Ma jorVersion, Stack_MinorVersion) ; 

stk = _somdNewOb ject (SOMDOb jectMgr , Sev, "Stack", 

/* Verify successful object creation */ 
if ( OperationOK (Sev) ) 

{ 

while ( !_full(stk, Sev) ) 

{ 

_push(stk, Sev, num); 

somPrintf ("Top: %d\n", _top(stk, Sev) ) ; 
num += 100; 

} 



/* Test stack overflow exception */ 

_push(stk, Sev, num) ; 

OperationOK (sev) ; 

while ( !_empty(stk, Sev) ) 

{ 

somPrintf ( "Pop : %d\n", _pop(stk, Sev) ) ; 

} 

/* Test stack underflow exception */ 

somPrintf ( "Top Underflow: %d\n", _top(stk, Sev) ) ; 

OperationOK (sev) ; 

somPrintf ( "Pop Underflow: %d\n", _pop(stk, Sev) ) ; 
OperationOK (sev) ; 




_push(stk, &ev, -10000); 

somPrintf ( "Top : %d\n", _top(stk, &ev) ) ; 

somPrintf ( "Pop : %d\n", _top(stk, &ev)); 

_somdDestroyOb ject (SOMD_Ob jectMgr, &ev, stk); 

if ( OperationOK (&ev) ) 

{ 

somPrintf ( "Stack test successfully completed . \n"); 



SOMD_Uninit (&ev) ; 

SOM_UninitEnvironment (&ev) ; 

return (0) ; 

} 



boolean OperationOK (Environment *ev) 

{ 

char *exID; 

switch (ev->_major) 

{ 

case SYSTEM_EXCEPTION : 

exID = somExceptionld (ev) ; 

somPrintf ( "System exception: %s\n", exID) ; 
somdExceptionFree (ev) ; 
return (FALSE) ; 

case USER_EXCEPTION : 

exID = somExceptionld (ev) ; 

somPrintf ( "User exception: %s\n", exID); 

somdExceptionFree (ev) ; 

return (FALSE) ; 

case NO_EXCEPTION : 
return (TRUE) ; 

default : 

somPrintf (" Invalid exception type in Environment An") ; 
somdExceptionFree (ev) ; 
return (FALSE) ; 




Let's step through the differences. 

First, every DSOM program must include the file <somd.h> (when using C ++, <somd.xh>). This file defines constants, global variables, and 
run-time interfaces used by DSOM. Usually, this file is sufficient to establish all necessary DSOM definitions. 

Next, DSOM requires its own initialization call. 

SOMD_Init (Sev) ; 



The call to SOMDJnit initializes the DSOM run-time environment SOMDJnit must be called before any DSOM run-time calls are made. A 
side effect of calling SOMDJnit is that a run-time object, called the DSOM Object Manager, is created, and a pointer to it is stored in the 
global variable, SOMD_ObjectMgr, for programming convenience. The DSOM Object Manager provides basic run-time support for clients 
to find, create, destroy, and identify objects. The Object Manager is discussed in detail in the section entitled "Basic Client Programming." 

Next, the local stack creation statement, 

stk = StackNewf); 



was replaced by 



stk = _somdNewOb ject (SOMD_Ob jectMgr , Sev, "Stack", 



The call to somdNewObject asks the DSOM Object Manager (SOMD_ObjectMgr) to create a "Stack" object, wherever it can find an 




implementation of "Stack". (There are other methods with which one can request specific servers.) If no object could be created, NULL is 
returned, and an exception is raised. Otherwise, the object returned is a "Stack" proxy. 



Note: On AIX, the following call may be needed before the somdNewObject call, if the "Stack" class implementation has been linked 
directly with the program executable (vs. using a dynamic link library, or DLL). This call will properly initialize the class for use by 
DSOM (this initialization is done in SOMInitModulefor DLLs): 



StackNewClass (Stack_Ma jorVersion, Stack_MinorVersion) ; 



A proxy is an object that is a local representative for a remote target object. A proxy inherits the target object's interface, so it responds to 
the same methods. Operations invoked on the proxy are not executed locally, but are forwarded to the "real" target object for execution. The 
client program always has a proxy for each remote target object on which it operates. 

From this point on, the client program treats the "Stack" proxy exactly as it would treat a local "Stack". The "Stack" proxy takes responsibility 
for forwarding requests to, and yielding results from, the remote "Stack". For example, 

_push (stk, &ev, num) ; 



causes a message representing the method call to be sent to the server process containing the remote object. The DSOM run-time in the 
server process decodes the message and invokes the method on the target object. The result (in this case, just an indication of completion) 
is then returned to the client process in a message. The DSOM run time in the client process decodes the result message and returns any 
result data to the caller. 

At the end of the original client program, the local "Stack" was destroyed by the statement, 

_somFree (stk) ; 



whereas, in the client program above, the "Stack" proxy and the remote "Stack" are destroyed by the statement, 

_somdDestroyOb ject (SOMD_Ob jectMgr , Sev, stk) ; 

If the client only wants to release its use of the remote object (freeing the proxy) without destroying the remote object, it can call the 

somdReleaseObject method instead of somdDestroyObject. 

Finally, the client must shut down DSOM, so that any operating system resources acquired by DSOM for communications or process 
management can be returned: 

SOMD_Uninit (Sev) ; 

This call must be made at the end of every DSOM program. 



Using specific servers 



In DSOM, the process that manages a target object is called the object's server. Servers are implemented as programs that use SOM 
classes. Server implementations are registered with DSOM in an Implementation Repository. The tmp/ementat/on Ftepos/tory is a database 
queried by clients in order to find desired servers, and queried by DSOM in order to activate those servers upon demand. 

The example above placed no constraints on the DSOM Object Manager as to where the remote "Stack" object should be created. The 
somdNewObject call creates a remote object of a specified class in an arbitrary server that implements that class. Flowever, the DSOM 
Object Manager provides methods for finding specific servers. 

For example, the client program above can be modified slightly to find a specific server named "StackServer", which has already been 
registered in DSOM's Implementation Repository. (Note that the programmer knew or discovered that the "StackServer" server 
implementation supports the "Stack" class.) The highlighted lines below show the changes that were made: 

((include <somd.h> 

((include <stack.h> 

int main(int argc, char *argv[]) { 

Stack stk; 

Environment e; 

SOMDServer server; 




SOM_InitEnvironment (&e) ; 

SOMD_Init (&e) ; 

server = 

_somdFindServerByName (SOMD_Ob jectMgr, &e, "StackServer") ; 
stk = _somdCreateObj (server, &e, "Stack", 

_push (stk, &e, 100) ; 

_push (stk, &e, 200) ; 

_pop (stk, &e) ; 

if ( !_empty (stk, &e) ) somPrintf ( "Top : %d\n", _top (stk, &e) ) ; 

_somdDeleteOb j (server, &e, stk) ; 

_somdReleaseOb ject (SOMD_Ob jectMgr, &e, stk); 

_somdReleaseOb ject (SOMD_Ob jectMgr, &e, server); 

SOMD_Uninit (&e) ; 

SOM_UninitEnvironment (&e) ; 

return ( 0 ) ; 



This version of the program replaces the somdNewObject operation with calls to somdFindServerByName and somdCreateObj. The 
somdFindServerByName method consults the Implementation Repository to find the DSOM server implementation whose name is 
"StackServer", and creates a server proxy, which provides a connection to that server. Every DSOM server process has a server object 
that defines methods to assist in the creation and management of objects in that server. Server objects must be instances of SOMDServer 
or one of its subclasses. The somdFindServerByName returns a proxy to the SOMDServer object in the named server. 

Once the client has the server proxy, it can create and destroy objects in that server. The somdCreateObj call creates an object of the class 
"Stack" in the server named "StackServer”. 

To free the remote "Stack" object, the example shows a somdDeleteObj request on the stack object's server. Next, somdReleaseObject 
requests are made on the DSOM Object Manager, to free the stack proxy and the server proxy in the client. (Note that these three calls are 
equivalent to the somdDestroyObject call in the previous example.) 



A note on finding existing objects 



The two examples above show how clients can create a remote, transient object for their exclusive use. Clients may want to find and use 
objects that already exist. In that case, the calls to somdNewObject or somdCreateObj would be replaced with other "lookup" calls on 
some directory object that would take an object name or identifier and return a proxy to the remote object. 

Such a directory object could be implemented by the application as a persistent SOM object, using DSOM to share it among processes. 
The basic mechanisms that DSOM provides for naming and locating objects will be discussed in section "Basic Client Programming." 



"Stack" server implementation 



A server consists of three parts. First, a "main" program, when run, provides an address space for the objects it manages, and one or more 
process "threads" that can execute method calls. (Windows and AIX currently do not have multi-thread support, while OS/2 and AIX 4.1 do.) 
Second, a server object, derived from the SOMDServer class, provides methods used to manage objects in the server process. Third, one 
or more class libraries provide object implementations. Usually these libraries are constructed as dynamicat/y /inked '/ibraries (DLLs), so 
they can be loaded and linked by a server program dynamically. 

In this simple example, we can use the default DSOM server program, which is already compiled and linked. The default server behaves as 
a simple server, in that it simply receives and executes requests continuously. The default server creates its server object from the class, 
SOMDServer. The default server will load any class libraries it needs upon demand. 

The "Stack" class library, "stack.dll", can be used without modification in the distributed application. This is possible because the "Stack" 
class is "well formed"; in other words, there are no methods that imp/icit/y assume the c/ient and the object are in tbe same address space. 



Thus, by using the default server and the existing class library, a simple "Stack" server can be provided without any additional programming! 




An application may require more functionality in the server program or the server object than the default implementations provide. A 
discussion on how to implement server programs and server objects is found later in this chapter, in section 6.4, "Basic Server 
Programming". 



Compiling the application 



DSOM programs and class libraries are compiled and linked like any other SOM program or library. The header file "somd.h" (or for C++, 
"somd.xh") should be included in any source program that uses DSOM services. DSOM run-time calls can be resolved by linking with the 
SOMobjects Toolkit library: "libsomtk.a" on AIX and "somtk.lib" on OS/2 or Windows. (The DSOM DLL(s) - "somd.dll", for AIX or OS/2, or 
"somdl .dll" and "somdl .dll" for Windows - will be loaded at run time.) For more information, see "Compiling and linking" in Chapter 3, "Using 
SOM classes in Client Programs," and the same topic in Chapter 5, "Implementing Classes in SOM." 



Installing the implementation 



Before the application can be run, certain environment variables must be set and the stack class and server implementations must be 
registered in the SOM Interface Repository and DSOM Implementation Repository. 



Setting environment variables 



Several environment variables are used by SOM and DSOM. These variables need to be set before registering the DSOM application in the 
Interface and Implementation Repositories. 

For this example, the following environment variables could be set as shown. A full description of the environment variables and how to set 
them is given in section 6.6, "Configuring DSOM." 

On AIX (in the syntax of the default shell, /bin/ksh): 

export HOSTNAME=machine3 

export SOMIR=$SOMBASE/ etc/som. ir : /u/myuserid/my . ir 
export SOMDDIR=/u/myuserid/ somddir 

export LIBPATH=$LIBPATH : $SOMBASE/lib : /u/myuserid/lib 



On OS/2: 

set USER=pat 

set HOSTNAME=machine3 

set SOMDDIR=c : \somddir 

rem *** The following variables are set in CONFIG.SYS by 

rem *** the install program on OS/2, assuming n c:\som" is the 

rem *** value of %SOMBASE% supplied by the user. 

set SOMIR=c : \som\etc\som. ir; som. ir 

set LIBPATH= . ; c : \som\lib; <previous LIBPATH> 



On Windows: 

set USER=pat 

set HOSTNAME=machine3 

set SOMDDIR=c : \somddir 

rem *** The following variables are usually set in AUTOEXEC.BAT 
rem *** by the install program on Windows, assuming "c:\som" 
rem *** is the value of %SOMBASE% supplied by the user, 
set SOMIR=c : \som\etc\som. ir : som. ir 
set PATH= . ; c : \som\lib; <previous PATH> 




USER identifies the user of a DSOM client application. DSOM sends the USER ID with every remote method call, in case the remote object 
wishes to perform any access control checking. This is discussed later in the section "Basic Server Programming." (Note that USER is 
usually set automatically by AIX when a user logs in.) 

HOSTNAME identifies the name of each machine running DSOM. 

SOMIR gives a list of files that together constitute the Interface Repository. The IR is used by DSOM to guide the construction and 
interpretation of request messages. For DSOM, it is preferable to use full pathnames in the list of IR files, since the IR will be shared by 
several programs that may not all reside in the same directory. 

SOMDDIR gives the name of a directory used to store DSOM configuration files, including the Implementation Repository. 

LIBPATH (on AIX and OS/2) or PATH (on Windows) gives a list of directories where DLLs can be found. 



Registering the class in the Interface Repository 



Before an object can be accessed remotely by DSOM, it is necessary to register the class's interface and implementation in the Interface 
Repository (IR). DSOM uses the interface information when transforming local method calls on proxies into request messages transmitted to 
remote objects. 

DSOM servers also consult the IR to find the name of the DLL for a dynamically loaded class. The DLL name for the "Stack" class must be 
specified using the dllname="stack.dM" modifier in the implementation statement of the "Stack” IDL. The Interface Repository is described 
in detail in Chapter 7, "The Interface Repository Framework." 

The IDL specification of "Stack" is compiled into the Interface Repository using the following command: 

sc -u -sir stack. idl (on AIX or OS/2) 

some -u -sir stack. idl (on Windows) 



When a class has not been compiled into the Interface Repository, DSOM will generate a run-time error when an attempt is made to invoke 
a method from that class. The error indicates that the method's descriptor was not found in the IR. 



Registering the server in the Implementation Repository 



It is necessary to register a description of a server's implementation in the Implementation Repository. DSOM uses this information to assist 
clients in finding servers, and in activating server processes upon demand. 

For this example, where the default server is used, we need only to identify the server's name, and the class that the server implements. 
This is accomplished using the regimpl utility discussed in section 6.6, "Configuring DSOM Applications". The following commands define a 
default server, named "StackServer", which supports the Stack class: 

regimpl -A -i StackServer 
regimpl -a -i StackServer -c Stack 



Running the application 



This section discusses: 

• Starting the DSOM daemon 

• Running the client 



Starting the DSOM c/aemon 




Before running a DSOM application, the DSOM daemon, somdd, must be started. 

• On AIX or OS/2, the daemon can be started manually from the command line, or it could be started automatically from a start-up 
script run at boot time. It may be run in the background with the commands somdd& on AIX and start somdd on OS/2. (The 
somdd program requires no parameters. An optional -q parameter can be used to set "quiet" mode, to suppress messages.) 

• On Windows, the daemon can be started with the DSOM Daemon icon in the SOM icon group or started in Windows from the 
Run option of the file menu. The DSOM Daemon icon will change colors to indicate the daemon is ready, after which client and 
server programs can be started. 

The somdd daemon is responsible for establishing a "binding" (that is, a connection) between a client process and a server. It 
will activate the desired server automatically, if necessary. The server can also be started manually prior to starting the client 
program, using the command dsom start stackServer. 

Running the c/ient 

Once the DSOM daemon is running, the application may be started. This is accomplished by running the client program. If the StackServer 
is not running, it will be started automatically by the DSOM daemon when the client attempts to invoke a method on one of its objects. After 
the client program ends, the server will continue to run, accepting connections from new clients. To terminate the server, use the command 

dsom stop stackServer. 



"Stack" example run-time scenario 



The following scenario steps through the actions taken by the DSOM run time in response to each line of code in the second "Stack" client 
program presented above. The illustration following the scenario shows the processes, and the objects within them, that participate in these 
actions. 

• Initialize an environment for error passing: 



SOM_InitEnvironment (Se) ; 



Initialize DSOM: 



SOMD_Init (Se) ; 



This causes the creation of the DSOM Object Manager (with SOMDObjectMgr interface). The global variable SOMD_ObjectMgr points to this 
object. 

• Initialize "Stack" class object: 



StackNewClass (Stack_Ma jorVersion, Stack_MinorVersion) ; 



Find the "StackServer" implementation and assign its proxy to the variable server: 



server = _somdFindServerByName (SOMD_Ob jectMgr , &e, "StackServer"); 



This causes the creation of the server proxy object in the client process. Proxy objects are shown as shaded circles. Note that the "real" 
server object in the server process is not created at this time. In fact, the server process has not yet been started. 

• Ask the server object to create a "Stack" and assign "Stack" proxy to variable stack. 




stk = _somdCreateObj (server, Se, "Stack", 



This causes somdd, the DSOM daemon (which is already running) to activate the stack server process (by starting the "generic" server 
program). The stack server process, upon activation, creates the "real" SOMDServer object in the server process. The SOMDServer object 
works with the DSOM run time to create a local "Stack" object and return a "Stack" proxy to the client. (The details of this procedure are 
deferred until section 6.4, "Basic Server Programming”.) 

• Ask the "Stack" proxy to push 1 00 onto the remote stack: 



.push (stk, se, 100) ; 



This causes a message representing the method call to be marshalled and sent to the server process. In the server process, DSOM 
demarshals the message and, with the help of the SOMDServer, locates the target "Stack" object upon which it invokes the method ("push"). 
The result (which is void in this case) is then passed back to the client process in a message. 

• Invoke more "Stack" operations on the remote stack, via the proxy: 

_push (stk, se, 200) ; 

_pop (stk, &e) ; 

if ( !_empty (stk, &e) ) t = _top (stk, &e) ; 

• Explicitly destroy both the remote stack, the stack proxy, and the server proxy: 

_somdDeleteOb j (server, Se, stk) ; 

_somdReleaseOb ject (SOMD_Ob jectMgr , Se, stk) ; 

_somdReleaseOb ject (SOMD_Ob jectMgr , Se, server) ; 

• Free the error-passing environment: 



SOM_UninitEnvironment (Se) ; 



This scenario has introduced the key processes in a DSOM application: client, server, and somdd. Also introduced are the key objects that 
comprise the DSOM run-time environment: the SOMD_ObjectMgr in the client process and the SOMD_ServerObject in the server process. 



Summary 



This example has introduced the key concepts of building, installing, and running a DSOM application. It has also introduced some of the 
key components that comprise the DSOM application run-time environment. 

The following sections, "Basic Client Programming," "Basic Server Programming," and "Implementing Classes," provide more detail on how 
to use, manage, and implement remote objects, respectively. 



Basic Client Programming 




For the most part, client programming in DSOM is exactly the same as client programming in SOM, since DSOM transparently hides the fact 
that an object is remote when the client accesses the object. 

Flowever, a client application writer also needs to know how to create, locate, use, save, and destroy remote objects. (This is not done using 
the usual SOM bindings.) The DSOM run-time environment provides these services to client programs primarily through the DSOM Object 
Manager. These run-time services will be detailed in this section. Examples of how an application developer uses these services are 
provided throughout the section. 



DSOM Object Manager 



DSOM defines a DSOM Object Manager , which provides services needed by clients to create, find and use objects in the DSOM run-time 
environment. 

The DSOM Object Manager is derived from an abstract, generic "object manager" class, called ObjectMgr. This abstract ObjectMgr class 
defines a basic set of methods that support object creation, location (with implicit activation), and destruction. 

As an abstract class, ObjectMgr defines only an interface; there is no implementation associated with ObjectMgr. Consequently, an 
application should not create instances of the ObjectMgr class. 

An abstract Object Manager class was defined under the expectation that applications will often need simultaneous access to objects 
implemented and controlled by a variety of object systems. Such object systems may include other ORBs (in addition to DSOM), persistent 
object managers, object-oriented databases, and so forth. It is likely that each object system will provide the same sort of basic services for 
object creation, location, and activation, but each using a different interface. 

Thus, the ObjectMgr abstract class defines a simple and "universal" interface that can be mapped to any object system. The application 
would only have to understand a single, common ObjectMgr interface. Under this scheme, specific object managers are defined by 
subclassing the ObjectMgr class and overriding the ObjectMgr methods to map them into the object system-specific programming 
interfaces. 

DSOM's Object Manager, SOMDObjectMgr, is defined as a specific class of ObjectMgr. It defines methods for: 

• Finding servers that implement particular kinds of objects 

• Creating objects in servers 

• Obtaining object identifiers (string IDs) 

• Finding objects, given their identifiers 

• Releasing and destroying objects 

These functions will be discussed in the remainder of this section. 

Note: The OMG has standardized an "object lifecycle" service, which includes support for creating and destroying distributed objects. The 
DSOM Object Manager may be augmented in the future with an OMG-compliant lifecycle service. 



Initializing a client program 



A client application must declare and initialize the DSOM run time before attempting to create or access a remote object. The SOMDJnit 
procedure initializes all of the DSOM run time, including the SOMDObjectMgr object. The global variable, SOMD_ObjectMgr is initialized to 
point to the local DSOM Object Manager. 

A client application must also initialize all application classes used by the program. For each class, the corresponding 
<c/assName> NewClass call should be made. 

Note: In non-distributed SOM programs, the <c/assName> New macro (and the new operator provided for each class by the SOM C++ 
bindings) implicitly calls the procedure <c/ass/Vame> NewClass when creating a new object. This is not currently possible in DSOM 
because, when creating remote objects, DSOM uses a generic method that is not class-specific. 




This was shown in the "Stack" example in section 6.2. In a similar example of an application that uses "Car" and "Driver" objects, the 
initialization code might look like this: 

((include <somd.h> /* needed by all clients */ 

((include <Car.h> /* needed to access remote Car */ 

((include <Driver.h> /* needed to access remote Driver */ 

main ( ) 

{ 

Environment ev; /* ev used for error passing */ 

SOM_InitEnvironment (Sev) ; 

/* Do DSOM initialization */ 

SOMD_Init (Sev) ; 

/* Initialize application classes */ 

CarNewClass (Car_Ma jorVersion, Car_MinorVersion) ; 

DriverNewClass (Driver_Ma jorVersion, Driver_MinorVersion) ; 

} 



As shown, client programs should include the "somd.h" file (or, for C++ programs, the "somd.xh" file) in order to define the DSOM run#time 
interfaces. 

Note also that, since Environments are used for passing error results between a method and its caller, an Environment variable (ei/) must 
be declared and initialized for this purpose. 

The calls to "CarNewClass" and "DriverNewClass" are required if the client will be creating or accessing Cars and Drivers. The procedures 
"CarNewClass" and "DriverNewClass" create class objects for the classes "Car" and "Driver". When a DSOM Object Manager method like 
somdNewObject is invoked to create a "Car", it expects the "Car" class object to exist. If the class does not yet exist, the "ClassNotFound" 
exception will be returned. 



Exiting a client program 



At the end of a client program, the SOMDJJninit procedure must be called to free DSOM run-time objects, and to release system resources 
such as semaphores, shared memory segments, and so on. SOMDJJninit should be called even if the client program terminates 
unsuccessfully; otherwise, system resources will not be released. 

For example, the exit code in the client program might look like this: 



SOMD_Uninit (&e) ; 
SOM_UninitEnvironment ( & e ) ; 



Note also the SOMJJninitEnvironment call, which frees any memory associated with the specified Environment structure. 

Note: When a Windows DSOM client receives a WM-QUIT message while processing a remote method invocation, DSOM will clean up and 
terminate the client without returning to the client's WinProc or WinMain. 



Creating remote objects 



Distributed objects can be created in several different ways in DSOM. 



The client can create an object on any server that implements that class of object. 




The client can find a specific server upon which to create an object. 



• A server can create an object and register a reference to the object in some well-known directory. (An object reference contains 
information that reliably identifies a particular object.) 

The first two cases are discussed immediately below. The last case is discussed near the end of this section. 



Creating an object in an arbitrary server 



Following is an example of how to create a new remote object in the case where the client does not care in which server the object is 
created. In this situation, the client defers these decisions to the DSOM Object Manager (SOMD_ObjectMgr) by using the somdNewObject 
method call, which has this IDL definition: 



// (from file om.idl) 



SOMObject somdNewObject ( in Identifier objclass, in string hints); 

// Returns a new object of the named class. This is a "basic" 

// creation method, where the decisions about where and how to 
// create the object are mostly left up to the Object Manager. 

// However, the Object Manager may optionally define creation 
// "hints" which the client may specify in this call. 



Here is the example of how a remote "Car" would be created using somdNewObject: 

#include <somd.h> 

#include <Car.h> 

main ( ) 

{ 

Environment ev; 

Car car; 

SOM_InitEnvironment (&ev) ; 

SOMD_Init (&ev) ; 

/* create the class object */ 

CarNewClass (Car_Ma jorVersion, Car_MinorVersion) ; 

/* create a Car object on some server, let the 
Object Manager choose which one */ 
car = _somdNewOb ject (SOMD_Ob jectMgr, &ev, "Car", ""); 



The main argument to the somdNewObject method call is a string specifying the name of the class of the desired object. The last argument 
is a string that may contain "hints" for the Object Manager when choosing a server. In this example, the client is providing no hints. 
(Currently, the DSOM Object Manager simply passes the hints to the server object in a somdCreateObj call.) 



Proxy objects 



As far as the client program is concerned, when a remote object is created, a pointer to the object is returned. However, what is actually 
returned is a pointer to a proxy object, which is a local representative for the remote target object . 

Proxies are responsible for ensuring that operations invoked on it get forwarded to the "real" target object that it represents. The DSOM run 
time creates proxy objects automatically, wherever an object is returned as a result of some remote operation. The client program will 
always have a proxy for each remote target object on which it operates. Proxies are described further in the sections entitled "DSOM as a 
CORBA-compliant Object Request Broker" and "Advanced Topics". 




In the example above, a pointer to a "Car” proxy is returned and put in the variable "car". Any subsequent methods invoked on "car" will be 
forwarded and executed on the corresponding remote "Car" object. 

Proxy objects inherit behavior from the SOMDClientProxy class. 



Servers and server objects 



In DSOM, the process that manages a target object is called the object's server. Servers are implemented as programs that use SOM 
classes. The example above placed no constraints on the DSOM Object Manager as to which server should create the remote "Car" object. 
However, if the client desires more control over distribution of objects, the DSOM Object Manager provides methods for finding specific 
servers. 

Server implementations are registered with DSOM in an /mp/ementation Repository . Server implementations are described by a unique ID, 
a unique (user-friendly) name, the program name that implements the server, the classes that are implemented by the server, the machine 
on which the server is located, whether the server is multi-threaded, and so forth. (See section 6.6 for more information on registering server 
implementations.) A client can ask the DSOM Object Manager to find a particular server: 

■ By name 

By ID 

• By a class it supports 

When a client asks for a "server", it is given (a proxy to) a server object that provides interfaces for managing the objects in the server. 
There is one server object per server process. All server objects are instances of the SOMDServer class, or its subclasses. The default 
method provided by SOMDServer for creating objects is: 

// (from file somdserv . idl ) 

SOMObject somdCreateOb j (in Identifier objclass, in string hints) ; 

// Creates an object of the specified class. This method 
// may optionally define creation "hints" which the client 
// may specify in this call. (Hints are ignored by default.) 



Section 6.4 explains how to create application-specific server objects, derived from SOMDServer, which override SOMDServer methods 
and introduce their own methods for object management. 



Creating an object in a specific server 



The following example demonstrates how a client application creates a new object ir> a remote server chosen by the c/ient . The DSOM 
Object Manager method somdFindServerByName is used to find and create a proxy to the server object for the server implementation 
named "myCarServer". The method somdCreateObj is then invoked on the server object to create the remote "Car”. A proxy to the remote 
"Car" is returned. (The "Stack" client presented in the previous section used the same methods to create a remote "Stack".) 

/* find a specific Car server */ 
server = 

_somdFindServerByName (SOMD_Ob jectMgr , &ev, "myCarSe rver" ); 

/* create a remote Car object on that server */ 
car = _somdCreateObj (server, &ev, "Car", 

} 



Note: If the specified server does not provide any implementation of the desired class, a NULL pointer will be returned and a 
"ClassNotFound" exception will be raised. 



Three other methods can be invoked on the DSOM Object Manager to find server implementations: somdFindServer, 
somdFindServersByClass, and somdFindAnyServerByClass. The IDL declarations of these methods follow: 



SOMDServer somdFindServer (in Implld serverid) ; 



sequence<SOMDServer> somdFindServersByClass (in Identifier objclass); 
SOMDServer somdFindAnyServerByClass (in Identifier objclass); 



The somdFindServer method is similar to the somdFindServerByName method, except that the server's /mp/ementat/on /D (of type 
Implld) is used to identify the server instead of the server's user-friendly name (or "alias"). The implementation ID is a unique string 
generated by the Implementation Repository during server registration. (See section 6.6 for more details.) 

The somdFindServersByClass method, given a class name, returns a sequence of a// servers that support the given class. The client 
program may then choose which server to use, based on the server's name, program, or other implementation attributes (e.g., the server is 
multi-threaded). (See the topic below, "Inquiring about a remote object's implementation.") 

Finally, the somdFindAnyServerByClass method simply selects any one of the server implementations registered in the Implementation 
Repository that supports the given class, and returns a server proxy for that server. 

Once the server proxy is obtained, methods like somdCreateObj, shown in the example above, can be invoked upon it to create new 
objects. 



Inquiring about a remote object's implementation 



A client may wish to inquire about the (server) implementation of a remote object. All objects in a server, including the "server object", share 
the same implementation definition. This is common when using the somdFindServersByClass call, where a sequence of server proxies is 
returned, and some choice must be made about which to use. 

When a proxy is obtained by a client, the client can inquire about the underlying server implementation by obtaining its corresponding 
ImplementationDef. An ImplementationDef object contains a set of attributes that describe a server implementation. To get the 
ImplementationDef associated with a remote object, the get_implementation method (implemented on SOMDObject and inherited by 
SOMDClientProxy) can be called. 

For example, if a program has a proxy for a remote server object, it can get the ImplementationDef for the server with method calls similar to 
the following: 



ImplementationDef implDef; 
SOMDServer server; 



implDef = _get_implementation (server, &ev) ; 



Once the ImplementationDef has been obtained, the application can access its attributes using the _get_impl_xxx methods. 
The ImplementationDef class is discussed further in section 6.6, "Configuring DSOM." 



Destroying remote objects 



There are several ways of destroying objects or their proxies in DSOM, just as there are several ways to create objects. Remote objects can 
be asked to destroy themselves, or, the SOMDObjectMgr and the SOMDServer can participate in the deletion. 



Destroying objects via a proxy 



DSOM provides means for deleting remote objects via their proxies. For example, if somFree is invoked on a proxy, the somFree call gets 




forwarded directly to the target object, just like any other target method call. For example, 



_somFree (car) ; 

frees the remote car. Note that, by default, invoking somFree on the proxy does not free the proxy, only the remote object. Flowever, the 
following call can be issued as part of a client-program initialization, so that invoking somFree on a proxy frees both the remote object and 
the proxy: 

set_somd2 IsomFree (SOMD_Ob jectMgr , ev, TRUE); 

All subsequent invocations of somFree on a proxy object will result in both the remote object and the proxy being freed. 

To be explicit about whether the proxy or the remote object is being deleted, the methods somdTargetFree and somdProxyFree, defined 
on proxies, can be used: 

_somdTargetFree (car , Sev); 

frees the remote "Car" (but not the proxy) and 

_somdProxyFree (car, &ev) ; 

frees the proxy (but not the remote "Car"). 

Note: CORBA specifies a third method for deleting object references. (Proxies are a specialized type of object reference.) The method 

.release (car , Sev); 

deletes the proxy (but not the target object). 



Destroying objects via the DSOM Object Manager 



Plaving created a remote object with somdNewObject or somdCreateObj, the remote object and its local proxy may be destroyed by 
invoking the method somdDestroyObject on the DSOM Object Manager using the proxy as an argument. For example, 



/* create the car */ 

car = _somdNewOb ject (SOMD_Ob jectMgr, &ev, "Car", ""); 

/* destroy the car (and its proxy) */ 

_somdDestroyOb ject (SOMD_Ob jectMgr, &ev, car) ; 



If the client does not want to destroy the remote object, but is finished working with it, the somdReleaseObject method should be used 
instead, e.g., 

_somdReleaseOb ject (SOMD_Ob jectMgr, Sev, car) ; 



This deletes the local proxy, but not the remote object. 

Both somdDestroyObject and somdReleaseObject are defined on the ObjectMgr, so that the Object Manager is aware of the client's 
actions, in case it wants to do any bookkeeping. 

The object passed to either the somdDestroyObject method or the somdReleaseObject method can be either a local SOM object or a 
DSOM proxy object. When a local SOM object is passed, somdDestroyObject has the same behavior as somFree. If a local SOM object 
passed to somdReleaseObject, however, this has no effect. 




Destroying objects via a server object 



The somdDestroyObject method described above sends a request to delete a remote object to the object's server. It does so to ensure 
that the server has an opportunity to participate in, if not perform, the deletion. The method defined on the SOMDServer class for destroying 
objects is somdDeleteObj. If the client has a proxy for the server object, it can also invoke somdDeleteObj directly, instead of calling 

somdDestroyObject. 

Destroying objects via the server object, rather than asking the object itself (as in somFree or somdTargetFree), allows the server object 
do any clean-up that is needed. For simple applications, this may not be necessary, but for applications that provide their own 
application-tailored server objects, it may be critical. See, for example, the persistent server example in section 6.4, entitled "Basic Server 
Programming." 



Creating remote objects using user-defined metaclasses 



An application may wish to define its own constructor methods for a particular class, via a user-supplied metaclass. In this case, the 
somdNewObject method should not be used, since it simply calls the default constructor method, somNew, defined by SOMCIass. 

Instead, the application can obtain a proxy to the actual class object in the server process. It can do so via the somdGetClassObj method, 
invoked on the SOMDServer proxy returned by one of the somdFindServerXxx methods. The application-defined constructor method can 
then be invoked on the proxy for the remote class object. 

Note: The same issues apply to destructor methods. If the application defines its own destructor methods, they can be called via the class 
object returned by somdGetClassObj, as opposed to calling somdDestroyObject. 



The following example creates a new object in a remote server using an application-defined constructor method, "makeCar", which is 
assumed to have been defined in the metaclass of "Car", named "MetaCar". 

((include <somd.h> 

((include <Car.h> 
main ( ) 

{ 

Environment ev; 

SOMDServer server; 

Car car; 

MetaCar carClass; 

SOM_InitEnvironment (Sev) ; 

SOMD_Init (Sev) ; 

/* find a Car server */ 

server = _somdFindAnyServerByClass (SOMD_Ob jectMgr , Sev, "Car"); 

/* get the class object for Car */ 

carClass = (MetaCar) _somdGetClassObj (server, Sev, "Car"); 

/* create the car object */ 

car = _makeCar (carClass, Sev, "Red", "Toyota", "2-door"); 



Saving and restoring references to objects 



A proxy is a kind of "object reference". An object reference contains information that is used to identify a target object. 

To enable clients to save references to remote objects (in a file system, for example) or exchange references to remote objects (with other 
application processes), DSOM must be able to externalize proxies. To "externalize a proxy" means to create a string ID for a proxy that can 




be used by any process to identify the remote target object. DSOM must also support the translation of string IDs back into proxies. 



The DSOM Object Manager defines two methods for converting between proxies and their string IDs: somdGetldFromObject and 
somdGetObjectFromld. 

Here is an example client program that creates a remote "Car 11 object. It generates a string ID corresponding to the proxy, and saves the 
string ID to a file for later use. 

♦include <stdio.h> 

♦include <somd.h> 

♦include <Car.h> 
main ( ) 

{ 

Environment ev; 

Car car; 

string somdOb jectld; 

FILE* file; 

SOM_InitEnvironment (Sev) ; 

SOMD_Init (Sev) ; 

/* create a remote Car object */ 

car = _somdNewObject (SOMD_Ob jectMgr , Sev, "Car", ""); 

/* save the reference to the object */ 

somdObjectld = _somdGetIdFromOb ject (SOMD_Ob jectMgr , Sev, car) ; 
file = fopen ( ”/u/ joe/mycar " , "w"); 

fprintf (file, "%s", somdObjectld); 



Next is an example client program that retrieves the string ID and regenerates a valid proxy for the original remote "Car" object (assuming 
the remote "Car" object can still be found in the server). 



Environment ev; 

Car car; 

char buffer [256]; 
string somdObjectld; 
FILE* file; 



/* restore proxy from its string form */ 
file = fopen ( "/u/ joe/mycar " , "r"); 

somdObjectld = (string) buffer; 
fscanf(file, "%s", somdObjectld); 

car = _somdGetOb jectFromld (SOMD_Ob jectMgr , &ev, somdObjectld); 



Once the proxy has been regenerated, methods can be invoked on the proxy and they will be forwarded to the remote target object, as 
always. 

Note: The somdGetldFromObject and somdGetObjectFromld methods directly correspond to the CORBA methods 
ORB_object_to_string and ORB_string_to_object, defined on the ORB class. 



Finding existing objects 



The SOMDObjectMgr and SOMDServer classes support the methods described above, which allow clients to create objects in servers. 
However, it is also likely that clients will want to find and use objects that have already been created, usually by the servers that implement 
them. For example, a print service will create printer objects, and must then export them to clients. In that case, the calls to 
somdNewObject or somdCreateObj would be replaced with other "lookup" calls on some directory (server) object which would take an 
object name or identifier and return a proxy to a corresponding remote object. Likewise, the server that owns the object would register the 
exported object in the directory. 

It is important to understand that DSOM does not provide a directory service such as the one described. But such a directory object could be 
implemented by the application, where a table or collection object maps object names to proxies. The string IDs for the proxies in the 
directory object could be saved using a file (as above) or a persistent object (via the Persistence Framework of SOMobject Developer 




Toolkit). A directory server implemented using DSOM could be used to share the directory among processes. 

Upon a lookup call, the directory server could find the corresponding proxy (or its string ID) in the directory, and return it to the caller. 



Finding server objects 



The DSOM Object Manager can be used to find server object proxies using the somdFindServerXxx methods. However, it is important to 
point out that an application can also augment those services, by managing server proxies itself. Server proxies can be maintained in an 
application-specific directory, stored in a file, or passed from process to process, just as any other proxies. 



Invoking methods on remote objects 



As described earlier, DSOM proxies are local representatives of remote objects, and as such, they can be treated like the target objects 
themselves. Method calls are invoked in exactly the same manner as if the object is local. This is true both for method calls using the static 
bindings (as most of our examples have shown), as well as for dynamic dispatching calls, where SOM facilities (such as the somDispatch 
method) are used to construct method calls at run time. 

CORBA 1.1 also defines a dynamic invocation interface that is implemented by DSOM. It is described later in section 6.9, "Advanced 
Topics". 

The DSOM run time is responsible for transporting any input method argument values supplied by the caller (defined by legal IDL types) to 
the target object in a remote call. Likewise, the DSOM run time transports the return value and any output argument values back to the caller 
following the method call. 

Note: DSOM uses the Interface Repository (IR) to discover the "signature" of a method (that is, the method's prototype). It is important that 
the contents of the IR match the method bindings used by the application program (i.e. the same IDL file is used to update the IR and 
to generate bindings). 



DSOM can make remote invocations only of methods whose parameter types are among the following IDL types: basic types (short, long, 
unsigned short, unsigned long, float, double, char, boolean, octet), enum, struct, union, sequence, string, array, any, and object. 

The members of a struct, union, sequence, or array and the value of an any, must also be from the above list of supported DSOM types. 

In addition to the preceding types, DSOM also supports method parameters of type pointer to one of the above types (for example, long*) 
Pointers to pointers are not supported, however, and pointers embedded within one of the above types (for example, a pointer within a 
struct) are not supported The "void *" type is also not supported. Currently, DSOM has the limitation that NULL pointer values cannot be 
returned as inout or out method arguments although it is expected that this limitation will be addressed in a future release. 

Types declared as SOMFOREIGN types are not currently supported by DSOM. Because the SOM soml is declared as a SOMFOREIGN 
type, this implies that any method having a parameter of type somld cannot be invoked remotely using DSOM. This restriction includes the 
SOM methods: somRespondsTo, somSupportsMethod, somGetMethodDescriptor, somGetMethodlndex, and 
somGetNthMethodlnfo. 

When a method parameter is an object type (that is, an instance of SOMObject or some class derived from SOMObject), a client program 
making a remote invocation of that method must pass an object reference for that parameter, rather than passing a local SOMObject, 
unless the client program is also DSOM server program, in which case DSOM will automatically convert the local object into an object 
reference. 

Methods having the procedure SOM IDL modifier cannot be invoked remotely using DSOM. This is because these "methods" are called 
directly, rather than via the normal method resolution mechanisms on which DSOM relies. 



Determining memory allocation and ownership 



When a method is invoked that returns a result of type string, sequence, or array, DSOM will allocate memory in the client's address space 
for the result. Ownership of this memory becomes the responsibility of the client program. When the client program has finished using it, the 




client should free the memory using the ORBfree function, rather than using free or SOMFree (This is because the memory has been 
allocated by DSOM using special memory management techniques; therefore, the client should ask DSOM to also free the memory.) 



When invoking a method using DSOM, the client program is responsible for providing storage for all in arguments and for all inout/out 
arguments, with the following exceptions: DSOM will allocate storage for a string or for the buffer field of a sequence when used as an 
out argument, and will allocate storage for the_value field of an any when used as an inout or out argument. This storage becomes the 
responsibility of the client program and should later be freed using ORBfree. For a string or sequence used as an inout argument, the out 
result is constrained to be no larger than the size of the in argument allocated by the client. 



Passing object references in method calls 



When pointers to objects are returned as method output values (as in the previous examples), DSOM automatically converts the object 
pointers (in the server) to object proxies in the client. 

Likewise, when a client passes object (proxy) pointers as input arguments to a method, DSOM automatically converts the proxy argument in 
the client to an appropriate object reference in the server. 

Note: If the proxy is for an object that is in the same server as the target object, DSOM gives the object reference to the server object for 
resolution to a SOM object pointer. Otherwise, DSOM leaves the proxy alone, since the proxy must refer to an object in some process 
other than the target's server. 



Memory management 



DSOM programs must manage four different kinds of memory resources: objects, object references, Environment structures, and blocks of 
memory. There are different techniques for allocating and releasing each kind of resource. 

Objects and object references 

Creating and destroying remote objects was discussed previously in this section (see "Creating remote objects" and "Destroying remote 
objects"). Creating and destroying local objects is described in section 3.2, "Using SOM Classes - the Basics," in Chapter 3, "Using SOM 
Classes in Client Programs." Object references are typically created automatically by DSOM as needed by the client program. They are also 
released in the client program by using either the release method or the somdProxyFree method. (The two methods are equivalent.) 

Environment structures 

When a client invokes a method and the method returns an exception in the Environment structure, it is the client’s responsibility to free the 
exception. This is done by calling either exception_free or somdExceptionFree on the Envirnmen structure in which the exception was 
returned. (The two functions are equivalent.) A similar function, somExceptionFree, is available for SOM programmers however DSOM 
programmers can use somdExceptionFree to free all exceptions (regardless of whether they were returned from a local or remote method 
call). 

Blocks of memory 

For allocating and releasing blocks of memory within a client program, SOM provides the SOMMalloc and SOMFree functions (analogous 
to the C "mallo" and "free" functions). The "Memory Management" section of Chapter 3 describes these functions. To release memory 
allocated by DSOM in response to a remote method call, however, DSOM client programs should use the ORBfree function 

For example, when a method is invoked that returns a result of type string, sequence, or array, DSOM will allocate memory for the result in 
the client's address space. Ownership of this memory becomes the responsibility of the client program. When finished using this memory, 
the client program should free it using the ORBfree function, rather than free or SOMFree. This is because the memory has been allocated 
by DSOM using special memory-management techniques; therefore, the client should ask DSOM to also free the memory. If the storage is 
freed using SOMFree rather than ORBfree, then memory leaks will result. 

The differences between the SOMFree and ORBfree functions are twofold: 

1 . First, SOMFree should only be used to free memory not allocated by DSO(for example, memory the client program allocated 
itself using SOMMalloc), while ORBfree should be used to free memory allocated by DSOM in response to a remote method 
call. 




2 . 



Second, SOMFee only frees a single block of memory (in the same way that the C "free" function does), while ORBfree will free 
an entire data structure, including any allocated blocks of memory within in. For example, if a remote method call returns a 
sequence of structs, and each struct contains a string, ORBfree will free, with a single call, not only the sequence's "_buffer” 
member, but also each struct and all the strings within the structs. Freeing a similar data structure using SOMFree would require 
multiple calls (one for each call to SOMMalloc used to build the data structure). 

Some programmers may wish to use a single function to free blocks of memory, regardless of whether they were allocated locally or by 
DSOM in response to a remote method call. For these programmers, DSOM provides a function, SOMDNoORBfree, which can be called 
just after calling SOMDJnit in the client program. (It requires no arguments and returns no value.) This function specifies that the client 
program will free all memory blocks using SOMFree, rather than ORBfree. In response to this call, DSOM will not keep track of the memory 
it allocates for the client. Instead, it assumes that the client program will be responsible for walking all data structures returned from remote 
method calls, while calling SOMFree for each block of memory within. 



Memory management for method parameters 



For each method, five SOM IDL modifiers are available to specify the method's memory-management policy (that is, whether the caller or 
the object owns the parameters' memory after the method is invoked). These modifiers are memory_management, caller_owns_result, 
caller owns parameters, object_owns_result, and object_owns_parameters. For a complete description of these modifiers and their 
meanings, see the section entitled "Implementation Statements" in Chapter 4, "SOM IDL and the SOM Compiler." 

Note that the memory-management policy for a particular parameter applies to the parameter and all the memory embedded within it (for 
example, if a struct is owned by the caller, then so are all the struct's members). Also note that the "object-owned" memory-management 
policy, specified by the object_owns_result and object_owns_parameters modifiers, is not supported by DSM for metods invoked using 
the Dynamic Invocation Interface (Dll). (This is because the "object-owned" policy is not CORBA-compliant, and because it precludes 
reusing Request objects to invoke a method multiple times.) 



The CORBA policy for parameter memory management 



When a class contains the SOM IDL modifier memory_management = corba, this signifies that all methods introduced by the class follow 
the CORBA specification for parameter memory management, except where a particular method has an explicit modifier 
(object_owns_result or object_owns_parameters) that indicates otherwise. The remainder of this section describes the CORBA 
specification for parameter memory management. 

Caller frees parameters and return results 

The CORBA memory-management policy specifies that the caller of a method is responsible for freeing all parameters and the return result 
after the method call is complete. This applies regardless of whether the parameter was allocated by the caller or the object (or, in the case 
of a remote method call, by DSOM). In other words, the CORBA policy asserts that parameters are uniformly "caller-owned". 

Allocation responsibilities 

Whether the parameter or return result should be allocated by the caller or by the object depends on the type of the parameter and its mode 
("in", "inout", "out", or "return"). In general, the caller is responsible for allocating storage for most parameters and return results. More 
specifically, CORBA requires that storage for all "in" arguments, for all "inout" or "out" arguments, and for all "return” results must be 
provided by the client program, with certain exceptions as itemized below. 

The object is responsible for allocating storage as follows: 

• for strings when used as "out" arguments or as "return" results 

• for the "_buffer" field of sequences when used as "out" arguments or as "return" results, 

• for the "_value" field of anys when used as "inout" or "out" arguments or as "return" results, 

• for pointer types when used as "inout" or "out" arguments or as "return" results, 

• for arrays when used as "return" results, and 

• for objects when used as "inout" or "out" arguments or as "return" results. 

Note: For "inout" strings and sequences, the "out" result is constrained to be no larger than the size of the "in" argument allocated by the 




client. 



Ownership of memory allocated in the above cases becomes the responsibility of the client program. For remote method calls, when a 
remote object allocates memory for a parameter or "return” value, DSOM subsequently allocates memory in the client's address space for 
the parameter or result. For a parameter/result that is an object (rather than a block of memory) DSOM automatically creates an object 
reference (a proxy object) in the client's address space. In each case, the memory or the proxy object becomes the responsibility of the 
client program and should later be freed by the client, using ORBfree for blocks of memory or release for proxy objects. 



The 'somdReleaseResources' method and object-owned 
parameters 



As stated earlier, the CORBA policy asserts that method parameters and return results are uniformly caller-owned. This means the method 
caller has the responsibility for freeing memory after invoking a method, regardless of whether the memory was allocated by the caller or the 
object. 

A class implementor can designate certain method parameters and results as object-owned, however, by using the object_owns_result 
and object_owns_parameters SOM IDL modifiers. These modifiers signify that the object, rather than the caller, is responsible for freeing 
the memory associated with the parameter/result. For "in" parameters, the object can free the memory any time after receiving it; for "inout" 
and "out" parameters, and for return results, the object will free the memory sometime before the object is destroyed. (See the section 
entitled "Implementation statements" in Chapter 4, "SOM IDL and the SOM Compiler," for more information on these modifiers.) 

When a DSOM client program makes a remote method invocation, via a proxy, and the method being invoked has an object-owned 
parameter or return result, then the client-side memory associated with the parameter/result will be owned by the caller's proxy, and the 
server-side memory will be owned by the remote object. The memory owned by the caller's proxy will be freed when the proxy is released by 
the client program. (The time at which the server-side memory will be freed depends on the implementation of the remote object.) 

A DSOM client can also instruct a proxy object to free all memory that it owns on behalf of the client without releasing the proxy (assuming 
that the client program is finished using the object-owned memory), by invoking the somdReleaseResource method on the proxy object. 
Calling somdReleaseResources can prevent unused memory from accumulating in a proxy. 

For example, consider a client program repeatedly invoking a remote method "get_string", which returns a string that is designated (in SOM 
IDL) as "object-owned". The proxy on which the method is invoked will store the memory associated with all the returned strings, even if the 
strings are not unique, until the proxy is released. If the client program only uses the last result returned from "get_string", then unused 
memory accumulates in the proxy. The client program can prevent this by invoking somdReleaseResources on the proxy object periodicall 
(for example, each time it finishes using the result of the last "get_string" call). 



Writing clients that are also servers 



In many applications, processes may need to play both client and server roles. That is, objects in the process may make requests of remote 
objects on other servers, but may also implement and export objects, requiring that it be able to respond to incoming requests. Details of 
how to write programs in this peer-to-peer style are explained in section 6.9, "Advanced Topics”. 



Compiling and linking clients 



All client programs must include the header file "somd.h" (or for C++, "somd.xh") in addition to any "< c/ass A/ame>.h" (or "<c/ass/Vame>.\ h") 
header files they require from application classes. All DSOM client programs must link to the SOMobjects Toolkit library: "libsomtk.a" on AIX 
and "somtk.lib" on OS/2. For more information, see the topic "Compiling and linking" in Chapter 3, "Using SOM Classes in Client Programs." 



Basic Server Programming 




Server programs execute and manage object implementations. That is, they are responsible for: 

• Notifying the DSOM daemon that they are ready to begin processing requests, 

• Accepting client requests, 

• Loading class library DLLs when required, 

• Creating/locating/destroying local objects, 

• Demarshalling client requests into method invocations on their local objects, 

• Marshalling method invocation results into responses to clients, and 

• Sending responses back to clients. 

As mentioned previously, DSOM provides a simple, "generic" server program that performs all of these tasks. All the server programmer 
needs to provide are the application class library(ies) DLL that the implementer wants to distribute. Optionally, the programmer can also 
supply an application#specific server class, derived from SOMDServer. (The SOMDServer class can be used by default.) The server 
program does the rest automatically. 

The "generic" server program is called somdsvr and can be found in /usr/lpp/som/bin/somdsvr on AIX and in 
%SOMBASE%\bin\somdsvr.exe on OS/2. 

Some applications may require additional flexibility or functionality than what is provided by the generic server program. In that case, 
application-specific server programs can be developed. This section discusses the steps involved in writing such a server program. 

To create a server program, a server writer needs to know what services the DSOM run-time environment will provide and how to use those 
services to perform the duties (listed above) of a server. The DSOM run-time environment provides several key objects that can be used to 
perform server tasks. These objects and the services they provide will be discussed in this section. Examples showing how to use the 
run-time objects to write a server are also shown. 



Server run-time objects 

There are three DSOM run-time objects that are important in a server: 

• The server's implementation definition (ImplementationDef), 

• The SOM Object Adapter (SOMOA), and 

• The application-specific server object (an instance of either SOMDServer or a class derived from SOMDServer). 



Server implementation definition 



A server's implementation definition must be registered in the implementation Repository before a server can be used. When a client 
attempts to invoke a method on a remote object, DSOM consults the Implementation Repository to find the location of the target object's 
server. 

An implementation definition is represented by an object of class ImplementationDef, whose attributes describe a server's ID, 
user-assigned alias, host name, program pathname, the class of its server object, whether or not it is multi-threaded, and so forth. 
Implementation IDs uniquely identify servers within the Implementation Repository, and are used as keys into the Implementation Repository 
when retrieving the ImplementationDef for a particular server. 

It is possible to change the implementation characteristics of a server, even to the point of using a completely different server program on 
another machine (with Workgroup DSOM). Thus, the implementation ID identifies a logical server, and the ImplementationDef describes 
the current implementation of that logical server. 

See the topic "Registering Servers and Classes" in section 6.6 for details on server registration. Two registration methods are described: 
"manual," (via the regimpl, the wregimpl, or the pregimpl utility) and "programmatic," ImpIRepository methods. 




When a server is initialized, it must retrieve a copy of its ImplementationDef, and keep it in a global variable (SOMDJmpIDefObject). This 
variab/e is used by the DSOM run time . (Client-only programs may leave the SOMDJmpIDefObject variable set to NULL.) 



SOM Object Adapter (SOMOA) 



The SOM Object Adapter (SOMOA) is the main interface between the server application and the DSOM run time. The SOMOA is 
responsible for most of the server duties listed at the beginning of this section. In particular, the SOMOA object handles all communications 
an interpretation of inbound requests and outbound results. When clients send requests to a server, the requests are received and 
processed by the SOMOA. 

The SOMOA works together with the server object to create and resolve DSOM references to local objects, and dispatch methods on 
objects. 

There is one SOMOA object per server process. (The SOMOA class is implemented as a singie instance class.) 



Server object 



Each server process contains a single server object , which has the following responsibilities for managing objects in the server: 

• Provides an interface to c/ient app/ications for basic object creation and destruction services, as well as any other 
application-specific object-management services that may be required by clients. For example, a print server may have a method 
that returns a list of all printers managed by that server. Clients may call this method to find out what printers are available. 

• Provides an interface to the SOM Object Adapter for support in the creation and management of DSOM object references 
(which are used identify an object in the server), and for dispatching requests. 

• The server class, SOMDServer, defines the base interface that must be supported by any server object. In addition, 
SOMDServer provides a default implementation that is suited to managing transient SOM objects in a server. This section will 
show how an application might override the basic SOMDServer methods and introduce new methods in order to tailor the server 
object functionality to a particular application. 



Server activation 



Server programs may be activated either 

• Automatica/iy by the DSOM daemon, somdd, or 

• Manua/iy via command line invocation, or under application control. 

When a server is activated automatically by somdd, it will be passed a single argument (in argvjlj) that is the imp/ementation /D assigned to 
the server implementation when it was registered into the Implementation Repository (discussed above and in section 6.6, "Configuring 
DSOM Applications"). This is useful when the server program cannot know until activation which "logical" server it is implementing. (This is 
true for the generic server provided with DSOM.) The implementation ID is used by the server to retrieve its ImplementationDef from the 
Implementation Repository. 

A server that is not activated by somdd may obtain its ImplementationDef from the Implementation Repository in any manner that is 
convenient: by ID, by alias, and so forth. Moreover, a server may choose to "register itself" dynamically, as part of its initialization. To do so, 
the server would use the programmatic interface to the Implementation Repository. 

For example, suppose that the server program "myserver" was designed so that it could be activated either automatically or manually. This 
requires that it be written to expect the implementation ID as its first argument, and to use that argument to retrieve its ImplementationDef 
from the Implementation Repository. If an application defines a server in the Implementation Repository whose implementation ID is 

2bcdc4f 2-0f 62f 780-7f-00-10005aa8afdc 

then "myserver" could be run as that server by invoking the following command: 




my server 2bcdc4 f 2-0f 62 f 7 80-7 f-00-10005aa8af dc 



AIX users should be aware that, unless the SetUserlD mode bit is set on the file containing the server program, the UID for the server 
process will be inherited from the somdd process. To set the SetUserlD mode bit from the AIX command line, type one of the following 
commands: 

chmod 4000 <filename> - or — 

chmod u+s <filename> 



where "<filename>" denotes the name of the file containing the server program. For additional details, see the "chmod" command in 
InfoExplorer or consult the "man" pages. 



Initializing a server program 



The following subjects are discussed in this section: 

• Initializing the DSOM run-time environment 

• Initializing the server's ImplementationDef 

• Initializing the SOM Object Adapter 

• When initialization fails 



Initializing the DSOM run-time environment 



The first thing the server program should do is to initialize the DSOM run time by calling the SOMDJnit function. This causes the various 
DSOM run-time objects to be created and initialized, including the Implementation Repository (accessible via the global variable 
SOMDJmpIRepObject), which is used in the next initialization step. 



Initializing the server's ImplementationDef 



Next, the server program is responsible for initializing its implementationDef, referred to by the global variable SOMDImpIDefObject. It is 
initialized to NULL by SOMDJnit. (For client programs it should be left as NULL.) If the server implementation was registered with the 
Implementation Repository before the server program was activated (as will be the case for all servers that are activated automatically by 
somdd), then the ImplementationDef can be retrieved from the Implementation Repository. Otherwise, the server program can register its 
implementation with the Implementation Repository dynamically (as shown in section 6.6, "Configuring DSOM applications"). 

The server can retrieve its ImplementationDef from the Implementation Repository by invoking the findjmpldef method on 
SOMDJmpIRepObject. It supplies, as a key, the implementation ID of the desired ImplementationDef. 

The following code shows how a server program might initialize the DSOM run-time environment and retrieve its ImplementationDef from 
the Implementation Repository. 

#include <somd.h> /* needed by all servers */ 
main(int argc, char **argv) 

{ 

Environment ev; 

SOM_InitEnvironment (&ev) ; 

/* Initialize the DSOM run-time environment */ 

SOMD_Init (&ev) ; 

/* Retrieve its ImplementationDef from the Implementation 
Repository by passing its implementation ID as a key */ 

SOMD_ImplDefOb ject = 

_f ind_impldef (SOMD_ImplRepOb ject , &ev, argv[l]); 




Initializing the SOM Object Adapter 



The next step the server must take before it is ready to accept and process requests from clients is to create a SOMOA object and initialize 
the global variable SOMD_SOMOAObject to point to it. This is accomplished by the assignment: 

S OMD_S OMOAOb j e c t = SOMOANewO; 



Note: The SOMOA object is not created automatically by SOMDJnit because it is only required by server processes. 

After the global variables have been initialized, the server can do any application-specific initialization required before processing requests 
from clients. Finally, when the server is ready to process requests, it must call the impl_is_ready method on the SOMOA: 

_impl_is_ready (SOMD_SOMOAObject, Sev, SOMD_ImplDef Ob ject ) ; 



The SOMOA will then set up a communications port for incoming messages, which it registers with the DSOM daemon. Once the DSOM 
daemon has been notified of the server's port, it assists client applications in "binding" (i.e., establishing a connection) to that server. 

The impl_is_ready method also causes the server object, whose class is defined in the server's ImplementationDef, to be created. The 
server object can be referenced through the global variable, SOMD_ServerObject. 



When initialization fails 



It is possible that a server will encounter some error when initializing itself. Servers must attempt to notify DSOM that their activation failed, 
using the activate_impl_failed method. This method is called as follows: 

/* tell the daemon (via SOMOA) that activation failed */ 

_activate_impl_f ailed (SOMD_SOMOAObject, sev, SOMD_ImplDefObject, rc) ; 

Server writers should be aware, however, that until the server's SOMDJmpIdefObject has been initialized, it is not possible to call the 
_activate_impl_failed method on the DSOM daemon. 

Note: A server program should not call activate_impl_failed once it has called impl_is_ready. 



Processing requests 



The SOMOA is the object in the DSOM run-time environment that receives client requests and transforms them into method calls on local 
server objects. In order for SOMOA to listen for a request, the server program must invoke one of two methods on SOMD_SOMOAObject. 
If the server program wishes to turn control over to SOMD_SOMOAObject completely (that is, effectively have SOMD_SOMOAObject go 
into an infinite request-processing loop), then it invokes the execute_request_loop method on SOMDSOMOAObject as follows: 

rc = _execute_request_loop (SOMD_SOMOAOb ject , &ev, SOMD_WAIT) ; 



Note: This is the way the DSOM provided "generic" server program interacts with SOMD_SOMOAObject. 



The execute_request_loop method takes an input parameter of type Flags. The value of this parameter should be either SOMD_WAIT or 
SOMD_NO_WAIT. If SOMD_WAIT is passed as argument, execute_request_loop will return only when an error occurs. If 




SOMD_NO_WAIT is passed, it will return when there are no more outstanding messages to be processed. SOMD_NO_WAIT is usually 
used when the server is being used with the event manager. See "Peer vs. client-server processes" in section 6.9, "Advanced Topics," for 
more details. 

If the server wishes to incorporate additional processing between request executions, it can invoke the execute_next_request method to 
receive and execute requests one at a time: 

for (; ; ) { 

rc = _execute_next_request (SOMD_SOMOAOb ject , &ev, SOMD_NO_WAIT) ; 

/* perform app-specific code between messages here, e.g., */ 
if (!rc) numMessagesProcessed++; 

} 



Just like execute_request_loop, execute_next_request has a Flags argument that can take one of two values: SOMD_WAIT or 
SOMD_NO_WAIT. If execute_next_request is invoked with the SOMD_NO_WAIT flag and no message is available, the method returns 
immediately with a return code of SOMDERROR_NoMessages. If a request is present, it will execute it. Thus, it is possible to "poll" for 
incoming requests using the SOMD_NO_WAIT flag. 



Exiting a server program 



When a server program exits, it should notify the DSOM run time that it is no longer accepting requests. This should be done whether the 
program exits normally, or as the result of an error. If this is not done, somdd will continue to think that the server program is active, allowing 
clients to attempt to connect to it, as well as preventing a new copy of that server from being activated. 

To notify DSOM when the server program is exiting, the deactivate_impl method defined on SOMOA should be called. For example, 

/* tell DSOM (via SOMOA) that server is now terminating */ 

_deactivate_impl (SOMD_SOMOAObject, Sev, SOMD_ImplDefObject) ; 



Note: For robustness, it would be worthwhile to add appropriate "exit handlers" or "signal handlers" to your application servers that call the 
deactivatejmpl method upon abnormal program termination. This ensures the the DSOM daemon is made aware of the server's 
termination, so that client connections are no longer allowed. 



Finally, at the end of a server program, the SOMDJJninit procedure must be called to free DSOM run-time objects, and to release 
semaphores, shared memory segments, and any other system resources. 

For example, the exit code in the server program might look like this: 



SOMD_Uninit (&e) ; 
SOM_UninitEnvironment ( & e ) ; 



Observe also the SOM_UninitEnvironment call, which frees any memory associated with the specified Environment structure. 

When a Windows DSOM server application receives a WM_QUIT message while processing incoming requests, the 
execute_request_loop method will return SOMDERROR_WMQUIT. When the server receives SOMDERROR_WMQUIT, it should perform 
its usual clean up and termination procedures. 



Managing objects in the server 



The following subjects are discussed in this section: 

• Object references, ReferenceData, and the ReferenceData table 

• Simple SOM object references 

• SOMDServer (default server-object class) 

• Creation and destruction of SOM objects 

• Mapping objects to object references 




Hints on the use of create vs. create_constant 
Mapping object references to objects 
Dispatching a method 



Object references, ReferenceData, and the ReferenceData 
table 

One of SOMOA's responsibilities is to support the creation of object references (SOMDObjects). Recall from the "Stack" example 
discussion (in Section 6.2) that an object reference is an exportable "handle" to an object and that proxies are examples of object 
references. The SOMOA interface supports three operations for creating object references: create, create_constant, and 
create_SOM_ref. 

The create and create_constant methods allow a serve to associate application-specific data about an object with an object reference for 
that object. This data, called reference data , is represented in a sequence of up to 1024 bytes of information about the object. This 
sequence, defined by the type ReferenceData, may contain the object's location, state, or any other characteristics meaningful to the 
application. Usually, ReferenceData is used by a server process to locate or activate an object in the server. ReferenceData, and hence 
the methods create and create_constant are usually only used in connection with persistent objects (objects whose lifetimes exceed that of 
the process that created them). 

The create method differs from the create_constant method in the following way: ReferenceData associated with an object reference 
constructed by create_constant is immutable whereas the the ReferenceData associated with an object reference created by create can 
be changed (via the changejd method). References created with create_constant return true when the method is_constant is invoked on 
them. 

The create method stores the ReferenceData in a FteferenceData tab/e associated with the server, while create_constant maintains the 
ReferenceData as a constant part of the object reference. The ReferenceData associated with an object reference (whether it was 
constructed using create or create_constant can be retrieved via the SOMOA method get_id. 

The IDL SOMOA interface declarations of create, create_constant, getjd, and changejd, and the SOMDObject interface declaration of 
is_constant are presented below. 

/* From the SOMOA interface */ 

sequence <octet,1024> Referencedata; 

SOMDObject create (in Ref erenceData id, in InterfaceDef intf, 
in ImplementationDef impl) ; 

SOMDObject create^constant ( in Ref erenceData id, 

in InterfaceDef intf, 
in ImplementationDef impl) ; 

Ref erenceData getjd (in SOMDObject objref ) ; 

void changejd (in SOMDObject objref, in Ref erenceData id) ; 

/* From the SOMDObject interface */ 
boolean is_constant () ; 



An example of how ReferenceData can be used by an application follows the description of SOMDServer objects in the next section 



Simple SOM object references 



In order to efficiently support the generation and interpretation of references to SOM objects, the SOMOA defines another method called 

create_SOM_ref. 

The create_SOM_ref method creates a simple DSOM reference (SOMDObject) for a local SOM object. The reference is "special" in that, 
unlike create and create_constant there is no user-supplied ReferenceData associated with the object and because the reference is only 
valid while the SOM object exists in memory. The SOMObject to which it refers can be retrieved via the get_SOM_object method. The 
is_SOM_ref method can be used to tell if the reference was created using create_SOM_ref or not. The IDL declarations for 




create_SOM_ref, get_SOM_object, and is_SOM_ref are displayed below: 

/* from SOMOA's interface */ 

SOMDObject create_SOM_ref (in SOMObject somobj, 

in ImplementationDef impl) ; 

SOMObject get_SOM_ob ject (in SOMDObject somref ) ; 

/* from SOMDObject's interface */ 

boolean is_SOM_ref ( ) ; 



SOMDServer (default server-object class) 



Every server has a server object that implements three kinds of activities: 

• Creation and destruction of SOM objects 

• Mapping between SOMObjects and SOMDObjects, and 

• Dispatching methods on SOM objects 

Additional, application-specific server methods (for initialization, server control, etc.) can be defined in a subclass of the SOMDServer class. 
The class of the server object to be used with a server is contained in the server's ImplementationDef. 

Following are the IDL declarations of the SOMDServer operations: 

// methods called by a client 

SOMObject somdCreateOb j (in Identifier objclass, in string hints) 

void somdDeleteObj (in SOMObject somobj); 

SOMClass somdGetClassOb j (in Identifier objclass) ; 

// methods called by SOMOA 

SOMDObject somdRefFromSOMOb j (in SOMObject somobj); 

SOMObject somdSOMOb jFromRef (in SOMDObject objref ) ; 

void somdDi spat chMet hod ( in SOMObject somobj, 

out somToken retValue, 
in somld methodid, 
in va_list ap) ; 



Creation and destruction of SOM objects 



The SOMDServer class defines methods for the basic creation of SOM objects in the server process (somdCreateObj), and for finding the 
SOM class object for a specified class (somdGetClassObj). With somdGetClassObj, a client can get a proxy to a class object on the 
server, so that methods introduced in the class's metaclass (for example, class-specific constructors, etc.) may be invoked directly on the 
class object. Examples of client use of these two methods were presented earlier in Sections 6.2 and 6.3. 

With somdDeleteObj, the client can involve the server object in object destruction. (The methods somdTargetFree and somFree are 
defined on the object themselves and do not involve the server object.) Involving the server object in object creation and destruction can be 
important for applications that need more control over how objects are created and destroyed, or if the application needs to keep track of an 
object's creation and destruction. 




Mapping objects to object references 



SOMDServer also defines methods that implement mappings between SOMObjects and SOMDObjects (object references) and a method 
for dispatching method calls on SOM objects. These methods are used by the SOM Object Adapter (SOMOA) when converting remote 
requests into method calls and results into responses. 

Recall from the topic "Proxy objects" in Section 6.3, "Basic Client Programming", that servers return proxies to remote objects as method 
results, not the remote objects themselves. Recall also that class libraries need not be designed to be distributed (that is, the code that 
implements the classes need not be aware of the existence of proxy objects at all). Thus, it is up to the DSOM run-time environment to 
ensure that proxies, rather than remote objects, are returned to clients. The SOMD_SOMOAObject and SOMD_ServerObject work 
together to perform this service. Whenever a result from a remote method call includes a SOMObject, the SOMD_SOMOAObject invokes 
the somdRefFromSOMObj method on SOMD ServerObject, asking it to create a SOMDObject from the SOMObject. 

The default implementation (i.e., SOMDServer's implementation) for somdRefFromSOMObj uses the create_SOM_ref method to return a 
"simple" reference for the SOMObject. Application-specific server objects (instances of a subclass of SOMDServer) may elect to use create 
or create_constant to construct the object reference if the application requires Reference Data to be stored. 



Hints on the use of create vs. create constant 



Enough context now exists so that the following question may be answered: "If object references constructed with create support 
changeable ReferenceData, but object references constructed with create_constant do not, why would I ever want to use 

create_constant?” 

Invocations of create add entries to a table called the ReferenceData Tab/e. The ReferenceData Table is persistent; that is, ReferenceData 
saved in it persists between server activations. Two calls to create with the same arguments do not return the same SOMDObject (per 
CORBA 1.1 specifications) That is, if create is called twice with the same arguments, two entries in the ReferenceData Table will be created. 
If a server using create wishes to avoid cluttering up the ReferenceData Table with multiple references to the same object, it must maintain 
a table of its own to keep track of the references it has created to avoid calling create twice with the same arguments. 

The create_constant method stores the ReferenceData as part of the SOMDObject's state; that is, it does not add entries to the 
ReferenceData Table. The create_constant method, then, might be used by a server that does not want to maintain a table of references 
nor pay the penalty of cluttering up the ReferenceData Table with multiple entries. 



Mapping object references to objects 



The somdSOMObjFromRef method maps SOMDObjects to SOMObjects. This method is invoked by SOMOA on the server object, for 
each object reference found as a parameter in a request. 

The default implementation for somdSOMObjFromRef returns the address of the SOMObject for which the specified object reference was 
create (using the somdRefFromSOMObj method). If the object reference was not created by the same server process, then an exception 
(BadObjref) is raised. The default implementation does not, however, verify that the original object (for which the object reference was 
created) still exists. If the original object has been deleted (for example, by another client program), then the address returned will not 
represent a valid object, and any methods invoked on that object pointer will result in server failure. Note: The default implementation of 
somdSOMObjFromRef does not check that the original object address is still valid because the check is very expensive and seriously 
degrades server performance. 

To have a server verify that all results from somdSOMObjFromRef represent valid objects, server programmers can subclass 
SOMDServer and override the somdSOMObjFromRef method to perform a validity check on the result (using the somlsObj function). For 
example, a subclass "MySOMDServer" of SOMDServer could implement the somdSOMObjFromRef method as follows: 

SOM_Scope SOMObject SOMLINK somdSOMObjFromRef (MySOMDServer somSelf, 

Environment * ev, 

SOMDObject objref) 

{ 

SOMObject obj; 

StExcep_INV_OB JREF *ex; 




/* MySOMDServerData *somThis = MySOMDServerGetData (somSelf ) ; */ 
MySOMDServerMethodDebug ( *MySOMDServer* , *somdSOMOb jFromRef " ) ; 

obj = MySOMDServer_parent_SOMDServer_somdSOMOb jFromRef (somSelf, 

ev, obj ref ) ; 

if (somlsOb j (ob j ) ) 
return (obj); 
else { 

ex = ( StExcep_INV_OB JREF *) 

SOMMalloc (sizeof (StExcep_INV_OB JREF) ) ; 
ex->minor = SOMDERROR_BadOb jref ; 
ex->completed = NO; 

somSetException (ev, USER_EXCEPTION, 

ex_StExcep_INV_OB JREF , ex) ; 

return (NULL) ; 




Dispatching a method 



After SOMOA (with the help of the local server object) has resolved all the SOMDObjects present in a request, it is ready to invoke the 
specified method on the target. Rather than invoking somDispatch directly on the target, it calls the somdDispatchMethod method on the 
server object. The parameters to somdDispatchMethod are the same as the parameters for SOMObject::somDispatch (see the 
SOMobjects Developer Toolkit: Programmers Reference Manual for a complete description). 

The default implementation for somdDispatchMethod in SOMServer simply invokes SOMObject::somDispatch on the specified target 
object with the supplied arguments. The reason for this indirection through the server object is to give the server object a chance to intercept 
method calls coming into the server process, if desired. 



Example: Writing a persistent object server 



This section shows an example of how to provide a server class implementation for persistent SOM objects. (The Persistence Framework of 
the full-capability SOMobjects Developer Toolkit can be used to write a persistent object s erver; an example of that type is given in the 
SOMobjects Deve/oper Too/kit Users Guic/e.J All of the persistent object management is contained in the server class; this class can be 
used with the DSOM "generic" server program, somdsvr. 

The following example describes a user-supplied server class "MyPServer” that is derived from SOMDServer. The "MyPServer" class 
introduces five new methods: 

• isPObj 

• assignRefDataToPObj 

• deletePObj 

• getRefDataFromPObj 

• activatePObjFromRefData 

and overrides four SOMDServer methods: 

• somdCreateObj 

• somdDeleteObj 

• somdRefFromSOMObj 

• somdSOMObjFromRef. 

The example shows how a server class might use and manage Reference Data in object references to find and activate persistent objects. 
The IDL specification for ''MyPServer" follows: 



interface MyPServer : SOMDServer { 

boolean isPObj (in SOMObject obj); 

void assignRefDataToPObj (in SOMObject pobj); 

void deletePObj (in SOMObject pobj); 

ReferenceData getRefDataFromPObj (in SOMObject pobj); 




SOMObject activatePOb jFromRefData (in ReferenceData 
#if def SOMIDL 



implementation { 
somdCreateOb j 
somdDeleteOb j 
s omdRe f F r omS OMOb j 
s omdS OMOb j F r omRe f 



override ; 
override ; 
override ; 
override : 



rd) ; 



#endif 

} ; 



The "isPObj" method returns TRUE if the object passed to it is a persistent object. It is implemented as follows: 

SOM_Scope boolean SOMLINK 

isPObj (MyPServer somSelf, Environment *ev, SOMObject obj) { 

return (obj && _somIsA(obj, MyPersistentOb jectNewClass ( 0 , 0) ) ; 

} 



The following two procedures override SOMDServer's implementations of somdCreateObj and somdDeleteObj. 

SOM_Scope SOMObject SOMLINK 

somdCreateObj (MyPServer somSelf , Environment *ev, 

Identifier objclass, string hints) 

{ 

/* create the object as usual */ 

SOMObject obj = 

parent_somdCreateOb j (somSelf, ev, objclass, hints) ; 

/* if obj is persistent, assign Ref Data to it */ 
if (_isPObj (somSelf , ev, obj))) { 

assignRefDataToPOb j (somSelf , ev, obj) 

} 

return (ob j ) ; 



The implementation of somdCreateObj first creates the object as usual by employing the implementation of SOMDServer (MyPServer's 
parent). If the newly created object is persistent, the job of "assignRefDataToPObj" is to associate with the object a piece of data that (1 ) 
identifies the object, (2) is retrievable from the object, and (3) can be coerced into ReferenceData so that it can be used to create a 
SOMDObject (an object reference). 

SOM_Scope void SOMLINK 

somdDeleteOb j (MyPServer somSelf, Environment *ev, SOMObject obj) 

{ 

/* is obj persistent, have the persistence framework delete it */ 
if (_isPObj (somSelf , ev, obj)) { 

_deletePObj (somSelf , ev, obj); 

} else /* obj is not persistent, so delete as usual */ 
parent_somdDeleteObj (somSelf , ev, obj); 

} 



The somdDeleteObj implementation, when the object to be deleted is persistent, invokes "deletePObj” to delete the object. When the object 
is not persistent, the SOMDServer implementation of somdDeleteObj deletes the object. 

The following two procedures override SOMDServer's implementations of the methods somdRefFromSOMObj and 
somdSOMObjFromRef: 

SOM_Scope SOMDObject SOMLINK 

somdRefFromSOMObj (MyPServer somSelf, Environment *ev, 

SOMObject obj) 

{ 

SOMDObject objref; 

/* is obj persistent */ 
if (_isPObj (somSelf, ev, obj { 

/* Create an object reference based on identifying data. */ 

ReferenceData rd = _getRefDataFromPOb j (somSelf , ev, obj); 

InterfaceDef intf = 

_lookup_id (SOM_InterfaceRepository, ev, somGetClassName (ob j ) ) ; 
objref = _create_constant (SOMD_SOMOAOb ject , ev, &rd, intf 

SOMD_ImplDefOb ject ) ; 

_somFree (intf) ; 

SOMFree (rd._buffer) ; 

} else /* obj is not persistent, so get Ref in usual way */ 




objref = parent_somdRef FromSOMOb j (somSelf , ev, obj); 
return (objref) ; 

} 



Method somdRefFromSOMObj is responsible for producing a SOMDObject (the"Ref" in somdRefFromSOMObj) from a SOMObject. As 
mentioned earlier, SOMOA exports two methods for creating SOMDObjects: create and create_constant. This implementation uses 
create_constant because it does not want to store the ReferenceData in the ReferenceData Table. If it did use create and store the 
ReferenceData in the persistent table, the server object would either (1) have to keep a persistent table that maps SOMObjects to 
SOMDObjects so that it didn't call create twice with the same arguments (recall that create always returns a new SOMDObject even when 
called twice with the same arguments), or (2) fill up the ReferenceData table with SOMDObjects that contain the same ReferenceData. 

The prerequisites for asking SOMOA to create a SOMDObject are (1) some ReferenceData to be associated with the SOMDObject, (2) an 
InterfaceDef that describes the interface of the object, and (3) an ImplementationDef that describes te object's implementation. The 
InterfaceDef is retrieved from the SOM Interface Repository using the object's class name as key. The ImplementationDef is held in the 
variable SOMDJmpIDefObject that is set when the server process is initialized. The "MyPServer" method "getRefDataFromPObj" is used 
to retrieve the identifying data from the object and coerce it into ReferenceData. With these three arguments, SOMOA's create_constant is 
called to create the SOMDObject. 

SOM_Scope SOMObject SOMLINK 

somdSOMOb jFromRef (MyPServer somSelf , Environment *ev, 

SOMDObject objref) 

{ SOMObject obj; 

/* test if objref is mine */ 
if (_is_constant (objref , ev) ) { 

/* objref was mine, activate persistent object myself */ 

ReferenceData rd = _get_id (SOMD_SOMOAOb ject , ev, objref) 

obj = _activatePOb jFromRefData (somSelf , ev, &rd) ; 

SOMFree (rd._buffer) ; 

} else 

/* it's not one of mine, let parent activate object */ 
obj = parent_somdSOMOb jFromRef (somSelf, ev, objref) ; 
return obj; 

I 



This implementation of somdSOMObjFromRef is a little different from the others in that the server object must determine whether the 
SOMDObject is one that it created (that is, one that represents a persistent object), or is just a SOMDObject that was created by the 
SOMDServer code (its parent). This is done by asking the SOMDObject if it is a "constant" object reference (that is, one created by 
create_constant). If the SOMDObject says that it is a "constant", then the "MyPServer" may safely assume that the SOMDObject 
represents a persisten object that it created. If the SOMDObject is determined to represent a persistent object, then its ReferenceData is 
used to locate/activate the object it represents (via the method "activatePObjFromRefData'j. 



Identifying the source of a request 



CORBA 1.1 specifies that a Basic Object Adapter should provide a facility for identifying the pr/nc/pa/ (or user) on whose behalf a request is 
being performed. The get_principal method, defined by BOA and impleented by SOMOA returns a Principal object, which identifies the 
caller of a particular method. From this information, an application can perform access control checking. 

In CORBA 1 .1 , the interface to Principal is not defined, and is left up to the ORB implementation. In the current release of DSOM, a 
Principal object is defined to have two attributes: 

userName (string) Identifies the name of the user who invoked a request. 

hostName (string) Identifies the name of the host from which the request originated. 

Currently, the value of the UserName attribute is obtained from the USER environment variable in the calling process. Likewise, the 
hostName attribute is obtained from the FIOSTNAME environment variable. This facility is intended to provide basic information about the 
source of a request, and currently, is not based on any specific authentication (i.e., "login") scheme. More rigorous authentication and 
security mechanisms will be considered for future DSOM implementations. 

The IDL prototype for the get_principal method, defined on BOA (SOMOA) is as follows: 

Principal get_principal (in SOMDObject obj, 

in Environment *req_ev) ; 




This call will typically be made either by the target object or by the server object, when a method call is received. The get_principal method 
uses the Environment structure associated with the request, and an object reference for the target object, to produce a Principal object that 
define the request initiator. 

Note: CORBA 1.1 defines a "tk_Principal" TypeCode which is used to identify the type of Principal object arguments in requests, in case 
special handling is needed when building the request. Currently, DSOM does not provide any special handling of objects of type 
"tk_Principal"; they are treated like any other object. 



Compiling and linking servers 



The server program must include the "somd.h" header file. Server programs must link to the SOMobjects Toolkit library: "libsomtk.a" on AIX, 
and "somtk.lib" or OS/2. 

For more information, see the topic "Compiling and linking" in Chapter 5, "Implementing Classes in SOM." 



Implementing Classes 



DSOM has been designed to work with a wide range of object implementations, including SOM class libraries as well as non-SOM object 
implementations. This section describes the necessary steps in using SOM classes or non-SOM object implementations with DSOM. 



Using SOM class libraries 



It is quite easy to use SOM classes in multi-process DSOM-based applications as exemplified by the sample DSOM application presented in 
section 6.2, "A Simple DSOM Example". In fact, in many cases, existing SOM class libraries may be used in DSOM applications without 
requiring any special coding or recoding for distribution. This is possible through the use of DSOM's generic server program, which uses 
SOM and the SOM Object Adapter (SOMOA) to load SOM class libraries on demand, whenever an object of a particular class is created or 
activated. 

The topic "Registering servers and classes" in section 6.6 "Configuring DSOM Applications" discusses how to register a server 
implementation consisting of a DSOM generic server process and one or more SOM class libraries. 



Role of DSOM generic server program 



The generic server program provides basic server functionality: it continuously receives and executes requests (via an invocation of the 
SOMOA's execute_request_loop method), until the server is stopped. Some requests result in the creation of SOM objects; the generic 
server program will find and load the DLL for the object's class automatically, if it has not already been loaded. 

When generic server program functionality is not sufficient for the particular application, application-specific server programs can be 
developed. For example, some applications may want to interact with a user or I/O device between requests. The previous section, entitled 
"Basic Server Programming," discussed the steps involved in writing a server program. 



Role of SOM Object Adapter 



The SOM Object Adapter is DSOM's standard object adapter. It provides basic support for receiving and dispatching requests on objects. As 




an added feature, the SOMOA and the server process's server object collaborate t automate the task of converting SOM object pointers into 
DSOM object references, and vice versa. That is, whenever an object pointer is passed as an argument to a method, the SOMOA and the 
server object convert the pointer to a DSOM bject reference (since a pointer to an object is meaningless outside the object's address space). 



Role of SOMDServer 



The server process's server object (whose default class is SOMDServer) is responsible for creating/destroying objects on the server via 
somdCreateObj, somdGetClassObj, and somdDeleteObj, for mapping between object references (SOMDObjects) and SOMObjects via 
somdRefFromSOMObj and somdSOMObjFromRef, and for dispatching remote requests to server process objects via 
somdDispatchMethod. These last three methods are invoked on the server object by the SOMOA when objects are to be returned to 
clients, when incoming requests contain object references, and when the method is ready to be dispatched, respectively. By partitioning out 
these mapping and dispatching functions into the server object, the application can more easily customize them, without having to build 
object adapter subclasses. 

SOMDServer can be subclassed by applications that want to manage object location, object activation, and method dispatching. An 
example of such an application (which provides a server class implementation for persistent SOM objects) is shown in section 6.4, "Basic 
Server Programming." 

These features of SOMOA and SOMDServer make it possible to take existing OM classes, which have been written for a single-address 
space environment, and use them unchanged in a DSOM application. More information on the SOMOA and server objects can be found in 
the "Basic Server Programming" section. 



Implementation constraints 



The generic server program (somdsvr), the SOMOA, and the SOMDServer make it easy to use SOM classes with DSOM. However, if 
there are any parts of the class implementation that were written expecting a single-process environment, the class may have to be modified 
to behave properly in a client/server environment. Some common implementation practices to avoid are listed below 

• Printing to standard output. Any text printed by a method will appear at the server, as opposed to the client. In fact, the server 
may not be attached to a text display device or window, so the text may be lost completely. It is preferred that any textual output 
generated by a method be returned as an output string. 

Note: Passing textual output between the client program and the called method via an "inout string" parameter is strong/y 
discouraged. As discussed in the CORBA 1.1 specification (page 94), the size of the output string is constrained by the 
size of the input string. If there was no input string value, the size of the output string would be constrained to 0 bytes. 
Instead, it is preferred that textual data be returned either as an output string (DSOM provides the storage), or by passing 
a character array buffer (client provides the storage). 

• Creating and deleting objects. Methods that create or delete objects may have to be modified if the created objects are 
intended to be remote. The calls to create local objects are different than the calls to create remote objects. 

• Using pointers to client-allocated memory in instance variables. Consider the following example: A class has a method that 
accepts a pointer to a data value created by the client (e.g., a string or a struct), and simply stores the pointer in an instance 
variable or attribute. However, in DSOM, the called method is passed a pointer to a copy of the value (in the request message 
body), but the copy is freed at the end of the request. If the data value is meant to persist between requests, the object is 
responsible for making its own copy of it. (The implementation of the "_set_printerName" method in the topic "Wrapping a printer 
API" later in this section is an example of a method performing such a copy.) 

• Using "procedure" methods. Methods having the procedure SOM IDL modifier cannot be invoked remotely using DSOM. This 
is because these "methods" are called directly, rather than by the normal method resolution mechanisms on which DSOM relies. 

In addition to those coding practices which simply do not "port" to a distributed environment, there are a few other restrictions that are 
imposed by DSOM's (current) implementation. 

• Using parameter types not supported by DSOM. DSOM can make remote invocations only of methods whose parameter 
types are among the following IDL types: basic types short, long, unsigned short, unsigned long, float, double, char, 
boolean, octet), enum struct, union, sequence, string, array, any, and object (an interface name, designating a pointer to an 
object that supports that interface). The members of a struct, union, sequence, or array, and the value of any any, must also 
be from the above list of supported DSOM types. 

In addition to the above types, DSOM also supports method parameters of type pointer to one of the above types (for example, 
long*). Pointers to pointers are not supported, however, and pointers embedded within one of the above types (for example, a 




pointer within a struct) are not supported. The "void*" type is also not supported. Currently, DSOM has the limitation that NULL 
pointer values cannot be returned as inout or out method arguments, although it is expected that this limitation will be 
addressed in the future release. 



Types declared as SOMFOREIGN types are not currently supported by DSOM. 

• Packing of structures used as method arguments. If a compiler option is used to pack or optimize storage of structs 
(including reordering of struct members) or unions, it is important to indicate the exact alignment of the structures using 
a//gnment mod/'f/ers expressed in the implementation section of the IDL file. This information must then be updated in the 
Interface Repository. 

Some applications may need to associate specific identification information with an object, to support application-specific object location or 
activation. In that case, an application server should create object references explicitly, using the create or create_constant method in 
SOMOA. A logical place to put these calls is in a subclass of SOMDServer, as it is the server object that is responsible for 
producing/activating objects from object references. 



Using other object implementations 



As an Object Request Broker, DSOM must support a wide range of object implementations, including non-SOM implementations. For 
example, in a print spooler application, the implementation of a print queue object may be provided by the operating system, where the 
methods on the print queue are executable programs or system commands. As another example, consider an application that uses a large, 
existing class library that is not implemented using SOM. Finally, consider a class library where persistence is implemented by something 
other than the Persistence Framework. 

In each of these examples, the application must participate in object identification, activation, initialization, and request dispatching. Each 
server supplies a server object (derived from SOMDServer) that works in conjunction with the SOMOA for this purpose. 



Wrapping a printer API 



Presented below is a simple example showing how an existing API could be "wrapped” as SOM objects. The API is admittedly trivial, but it is 
hoped that readers understand this simple example well enough to create more sophisticated applications of their own. 

The "API" wrapped in this example is comprised of two OS/2 system calls. The first one asks for a file to be printed on a specific printer: 

print /D : <printerName> <filename> 

The second one asks for the file currently being printed on device <printerName> to be cancelled. 

print /D : <printerName> /C 



Two IDL interfaces are declared in the module "PrinterModule": "Printer" and "PrinterServer". The "Printer" interface wraps the two system 
calls. The "PrinterServer" interface describes a subclass of SOMDServer. ”PrinterModule::PrinterServer" will be the class of the server 
object in the print-server application. 

#include <somdserv . idl> 

module PrinterModule { 

interface Printer : SOMObject { 
attribute string printerName; 
void print (in string fname) ; 
void cancel ( ) ; 

#ifdef SOMIDL 

implementation { 

printerName: noset; // memory to be allocated 
}; 

#endif 

}; 



interface PrinterServer : SOMDServer { 

#ifdef SOMIDL 

implementation { 




somdCreateObj : override; 
somdRef FromSOMOb j : override; 
somdSOMOb jFromRef : override; 
}; 

#endif 

}; 



Note that the "Printer" interface defines one attribute, "printerName", that will be used to identify the printer. It will be set when a "Printer" is 
created. Printer's two operations, "print" and "cancel", correspond to the two system commands the interface is encapsulating. The 
"PrinterServer" interface does not introduce any new attributes or operations. It does specify that three of SOMDServer's methods will have 
their implementations overridden. 

The next three method procedures show how the "Printer" interface is implemented for the "_set_printerName", "print", and "cancel" 
methods. Recall (from the earlier topic "Implementation constraints”) that "_set" methods for attributes must be explicitly implemented in 
order to allocate their memory, if data values need to persist between DSOM requests. 

SOM_Scope void SOMLINK PrinterModule_Printer_set_printerName ( 

PrinterModule_Printer somSelf, Environment *ev, string printerName) 

{ 

PrinterModule_PrinterData *somThis = 

PrinterModule_PrinterGetData (somSelf ) ; 

if (_printerName) SOMFree (_printerName) ; 

_printerName = (string) SOMMalloc (strlen (printerName) + 1); 
strcpy (_printerName, printerName) ; 

} 



SOM_Scope void SOMLINK PrinterModule_Printerprint ( 
PrinterModule_Printer somSelf, Environment *ev, string fname) 

{ 

long rc; 

PrinterModule_PrinterData *somThis = 
PrinterModule_PrinterGetData (somSelf) ; 
string printCommand = (string) 

SOMMalloc (strlen (_printerName) + strlen ( fname) + 10 + 1) ; 

sprintf (printCommand, "print /D:%s %s" , _printerName, fname) ; 
rc = system (printCommand) ; 
if (rc) raiseException (ev, rc) ; 

} 



SOM_Scope void SOMLINK PrinterModule_Printercancel ( 
PrinterModule_Printer somSelf, Environment *ev) 

{ 

long rc; 

PrinterModule_PrinterData *somThis = 
PrinterModule_PrinterGetData (somSelf) ; 
string printCommand = 

(string) SOMMalloc (strlen (_printerName) + 12 + 1); 

sprintf (printCommand, "print /D:%s /C" , _printerName) ; 
rc = system (printCommand) ; 
if (rc) raiseExeception (ev, rc) ; 

} 



Note: The implementation of the "raiseException" procedure shown in the example above must be provided by the application. However, it 
is not shown in this example. 



The three method procedures that implement the "PrinterServer" interface's three overridden methods of SOMServer are very similar to the 
method procedures of the "MyPServer" server-object class presented in the previous section (6.4), and therefore have not been shown here. 



Parameter memory management 



There are five SOM IDL modifiers available for specifying the memory-management policy for the parameters of a method (regardless of 




whether the caller or the object owns the parameters' memory after the method is invoked). These modifiers are: 



memory management, caller_owns_result, caller_owns_parameters, 
object_owns_result, and object_owns_parameters. 

See the section entitled "Implementation Statements" in Chapter 4, "SOM IDL and the SOM Compiler," for a complete description of these 
modifiers and their meanings. Note that the memory-management policy for a particular parameter applies to the parameter and all the 
memory embedded within it (for example, if a struct is owned by the caller, then so are all the struct’s members). 

When a class contains the memory_management = corba SOM IDL modifier, this signifies that all methods introduced by the class follow 
the CORBA specification for parameter memory management, except where a particular method has an explicit modifier 
(object_owns_result or object_owns_parameters) that indicates otherwise. For a description of the CORBA specification, see the earlier 
subtopic entitled "The CORBA policy for parameter memory management" (under the topic "Memory Management" in Section 6.3 of this 
chapter). 



Building and registering class libraries 



The generic server uses SOM's run-time facilities to load class libraries dynamically. Thus, dynam/ca//y //nked //bran'es (DLLs) should be 
created for the classes, just as they would be for non-distributed SOM-based applications. For more information, see the topic Creating a 
SOM class library in Chapter 5 "Implementing classes in SOM." 

During the development of the DLL, it is important to remember the following steps: 

• Export a routine called SOMInitModule in the DLL, which will be called by SOM to initialize the class objects implemented in that 
library. SOMInitModule should contain a <className>NewClass call for each class in the DLL. 

• For each class in the DLL, specify the DLL name in the class's IDL file. The DLL name is specified using the dllname=<name> 
modifier in the /mp/ementat/on statement of the interface definition. If not specified, the DLL filename is assumed to be the same 
as the class name. 

• For each class in the DLL, compile the IDL description of the class into the Interface Repository. This is accomplished by 
invoking the following command syntax: 



sc -sir -u stack. idl 



(On AIX or OS/2) 



Note: If the classes are not compiled into the Interface Repository, DSOM will generate a run-time error (30056: 

SOMDERROR_BadDescriptor) when an attempt is made to lookup the signature of a method in the class (for example, on 
a method call). 

Put the DLL in one of the directories listed in LIBPATFI for AIX or OS/2, or listed in PATPI for Windows. This is necessary for both 
OS/2, AIX, and Windows.) 



Configuring DSOM Applications 



The following subjects are discussed in this section: 

• Preparing the environment 

• Registering class interfaces 

• Registering servers and classes 

• The 'regimpl', ’pregimpl', 'wregimpl' registration utilities 

• Programmatic interface to the Implementation Repository 

• The 'dsom' server manager utility 

• Verifying the DSOM environment with 'somdchk' 

• Freeing interprocess communication resources on AIX 




Preparing the environment 




Some environment variables must be defined before running DSOM. 
and OS/2 environments. 


Unless noted, these environment variables are required in both the AIX 


HOSTNAME=<name> 


Each machine that is running DSOM must have its 
HOSTNAME variable set. 


USER=<name> 


USER specifies the name of the DSOM user running a client 
program. 


SOMIR=<file(s)> 


SOMIR specifies a list of files (separated by a colon on AIX 
and a semicolon on OS/2) which together make up the 
Interface Repository. See Chapter 7, "The Interface 
Repository Framework,” for more information on how to set 
this variable. 




Note: For DSOM, it is preferable to use full pathnames in the 
list of IR files, since the IR will be shared by several 
programs that may not all be started in the same 
directory. 


SOMSOCKETS=<name> 


SOMSOCKETS specifies the name of the SOM Sockets 
subclass that implements the sockets services. 




Note: For Workstation DSOM, this variable is effectively 
ignored. (However, it may be used by the Event 
Management Framework.) 


SOMDDIR=<directory> 


SOMDDIR specifies the directory where various DSOM files 
should be located, including the Implementation Repository 
files. See the later section in this chapter entitled "Registering 
servers and classes" for more information. 




Note: If this value is not set, DSOM will attempt to use a 
default directory: $SOMBASE/etc/dsom on AIX, and 
%SOMBASE%\ETC\DSOM on OS/2. 


SOMDPORT=<integer> 


In DSOM, servers, clients and DSOM daemons communicate 
with each other using a "sockets" abstraction. In particular 
DSOM clients establish connections to DSOM servers by 
communicating with the DSOM daemon, somdd, running on 
each server machine. The daemon is designed to listen for 
client requests on a well-known port. 




Normally, somdd will look in the /etc/services (for AIX) or 
%ETC%\SERVICES (for OS/2) file for its well-known port 
number. However, if the user has set the SOMDPORT 
environment variable, the value of SOMDPORT will be used 
and the "services” file will not be consulted. The user should 
pick a 1 6-bit integer that is not likely to be in use by another 
application (check the "services" file for ports reserved for use 
on your machine). Typically, values below 1024 are reserved 
and should not be used. 




Note: If there is no "services" file and the SOMDPORT 
environment variable is not set, DSOM will use a 
default port number (currently 9393). 


SOMDTIMEOUT=<integer> 


SOMDTIMEOUT specifies how long a receiver should wait for 
a message. The value should be expressed in seconds. The 
default value is 600 seconds (10 minutes). 


SOMDDEBUG=<integer> 


SOMDDEBUG may optionally be set to enable DSOM 
run-time error messages. If set to 0, error reporting is 
disabled. If set to 1 , error reporting is enabled. Error reports 
may be directed to the file named by SOMDMESSAGELOG, 
if set. 




SOMDMESSAGELOG=<file> 



SOMDMESSAGELOG may optionally be set to the name of a 
file where DSOM run-time error messages are recorded. If 
not set, error messages will be reported on the standard 
output device. 



SOMDNUMTHREADS=<integer> SOMDNUMTHREADS may optionally be set to the maximum 

number of requests threads created per server. If 
SOMDNUMTHREADS is not set, then a separate thread will 
be created for each request. This environment variable is only 
supported on OS/2. 

Note: You may want to verify your environment variable settings by running somdchk. See "Verifying the DSOM environment with 
'somdchk' later in this chapter. 



Registering class interfaces 



DSOM relies heavily on the Interface Repository for information on method signatures (that is, a description of the method's parameters and 
return value). It is important to compile the IDL for all application classes into the IR before running the application. 

For each class in the DLL, compile the IDL description of the class into the Interface Repository. This is accomplished by invoking the 
following command syntax: 

sc -sir -u stack. idl (on AIX or OS/2) 

If the default SOM IR (supplied with the SOMobjects Toolkit and Run times) is not used by the application, the user's IR must include the 
interface definitions for: 

• the appropriate Sockets class (if the SOMSOCKETS environment variable is set), 

• the server class (derived from SOMDServer), and 

• the definitions of the standard DSOM exceptions (found in file "stexcep.idl”) that may be returned by a method call. 



Registering servers and classes 



Implementation definitions: 

The Implementation Repository holds ImplementationDef objects The ImplementationDef class defines attributes necessary for the 
SOMOA to find and activate the implementation of an object. Details of the ImplementationDef object are not currently defined in the 
CORBA 1.1 specification: the attributes that have been defined are required by DSOM. 

Listed below is each available attribute, with its corresponding type in parentheses, followed by a description of its purpose: 

impl_id (string) Contains the DSOM-generated identifier for a server implementation. 

impl_alias (string) Contains the "alias" (user-friendly name) for a server implementation. 

impLprogram (string) Contains the name of the program or command file which will be 

executed when a process for this server is started automatically by 
somdd. If the full pathname is not specified, the directories specified in 
the PATH environment variable will be searched for the named 
program or command file. 

Optionally, the server program can be run under control of a "shell" or 
debugger, by specifying the shell or debugger name first, followed by 
the name of the server program. (A space separates the two program 
names.) For example, 




dbx myprogram 



impljlags (Flags) 



impl_server_class (string) 



will start the program ''myprogram" under control of "dbx". 

Servers that are started automatically by somdd will always be passed 
their impljd as the first parameter, in order to retrieve their 
ImplementationDef (if desired). 

Contains a bit-vector of flags used to identify server options (for 
example, the IMPLDEF_MULTI_TFIREAD flag indicates 
multi-threading). See the impldef . idl file for the complete set 
of valid ImplementationDef flags. Unused flag bits are reserved for 
future use by IBM. 

Contains the name of the SOMDServer class or subclass created by 
the server process. 



impl_refdata_file (string) 



Contains the full pathname of the file used to store ReferenceData for 
the server. 



impl_refdata_bkup (string) Contains the full pathname of the backup mirror file used to store 

ReferenceData for the server. This file can be used to restore a copy 
of the primary file in case it becomes corrupted. (It would be a good 
idea to keep the primary and backup files in different disk volumes.) 

impl_hostname (string) Contains the hostname of the machine where the server is located. 



The 'regimpl', 'pregimpl', 'wregimpl' registration utilities 



Before an implementation (a server program and class libraries) can be used by client applications, it must be registered with DSOM by 
running the implementation registration utility, regimpl (on AIX), pregimpl (on OS/2) or wregimpl (on Windows). The regimpl utility can 
also be executed from the DOS command line; this facility is available primarily for use in batch files. During execution of regimpl, 
pregimpl, or wregimpl, DSOM updates it database to include the new server implementation and the associated classes. This enables 
DSOM to find and, if necessary, to activate the server so that clients can invoke methods on it. 

Typically, DSOM users employ the generic SOM-object server program, described below. A discussion on how to write a specific 
(non-generic) server program is found in the earlier section, "Basic Server Programming." 



Registration steps Using 'regimpl' 



Registering a server implementation and its classes requires the steps described in the following paragraphs. 

First, make sure the SOMDDIR environment variable is defined to the name of the Implementation Repository directory, as discussed in the 
section "Preparing the Environment." 

Then, to run the regimpl utility, at the system prompt enter: 

> regimpl 

This brings up the DSOM Implementation Registration Utility menu, shown below. To begin registering the new implementation, select 
"I.Add" from the IMPLEMENTATION OPERATIONS section; that is, at the "Enter operation:" prompt, enter "1" (as shown in bold): 

DSOM IMPLEMENTATION REGISTRATION UTILITY 

(C) Copyright IBM Corp. 1992,1993. All rights reserved. 

Implementation data being loaded from: /u/xyz/dsomRepos/ 

[ IMPLEMENTATION OPERATIONS ] 

I.Add 2. Delete 3. Change 
4. Show one 5. Show all 6. List aliases 
[ CLASS OPERATIONS ] 




7. Add 8. Delete 9. Delete from all 10. List classes 
[ SAVE S EXIT OPERATIONS ] 

11. Save data 12. Exit 
Enter operation: 1 



The regimpl utility then issues several prompts for information about the server implementation (typical responses are shown in bold as an 
example). 

fmofementat/on a//as . Enter a "shorthand" name for conveniently referencing the registered server implementation while using regimpl: 

Enter an alias for new implementation: myServer 



Program name . Enter the name of the program that will execute as the server. This may be the name of one of the DSOM generic servers 
(discussed under the later topic "Running DSOM Servers") or a user-defined name for one of these servers. If the program is located in 
PATH, only the program name needs to be specified. Otherwise, the pathname must be specified. 

Enter server program name: (default: somdsvr) <return> 



Mu/tf-thread/no . Specify whether or not the server expects the SOM Object Adapter (SOMOA) to run each method in a separate thread or 
not. Notes: You must ensure that methods executed by the server are "thread safe". On AIX or Windows, you must also register a thread 
package to use a multi-threaded server. See "Customizing Multi-threading Services" in Chapter 5, "Implementing Classes in SOM". 



Allow multiple threads in the server? [y/n] 
(default: n) : n 



Server c/ass . Enter the name of the SOMDServer class or subclass that will manage the objects in the server. 

Enter server class (default: SOMDServer) : <return> 



Reference data file name . Enter the full pathname of the file used to store ReferenceData associated with object references created by this 
server. Note: A file name is required only if the server is using the create method to generate object references. 

Enter object reference file name (optional) : <return> 

Backup reference data fife name . Enter the full pathname of the backup file used to mirror the primary ReferenceData file for this server. 
Note: a file name is required only if (1) a primary reference data file has been specified, and (2) the application desires an online backup to 
be maintained. This file can be used to restore a copy of the primary file should it become corrupted. 

Enter object reference backup file name (optional) : <return> 



Host machine, name . This is the name of the machine on which the server program code is stored. The same name should be indicated in 
the HOSTNAME environment variable. (If "localhost" is entered, the contents of the HOSTNAME environment variable will be used. 

Enter host machine name : (default : localhost) <return> 



The regimpl system next displays a summary of the information defined thus far, and asks for confirmation before adding it. Enter "y" to 
save the implementation information in the Implementation Repository. 



Implementation id : 2bef c82b-13alle00-7f-00-10005ac9272a 

Implementation alias : myServer 

Program name : somdsvr 

Multithreaded : No 

Server class : SOMDServer 

Object reference file : 

Object reference backup...: 

Host Name : localhost 

The above implementation is about to be added. Add? [y/n] y 
Implementation 'myServer' successfully added 



Add c/ass . Once the server implementation is added, the complete menu reappears. The next series of prompts and entries will identify the 
classes associated with this server. To begin, from the CLASS OPERATIONS section, select "7. Add": 




[ IMPLEMENTATION OPERATIONS ] 

I. Add 2. Delete 3. Change 

4. Show one 5. Show all 6. List aliases 
[ CLASS OPERATIONS ] 

7. Add 8. Delete 9. Delete from all 10. List classes 
[ SAVE & EXIT OPERATIONS ] 

II. Save data 12. Exit 

Enter operation: 7 

C/assname . Enter the name of a class associated with the implementation alias. 

Enter name of class: classl 



/mo/ementat/on a //as. Enter the alias for the server that implements the new class (this should be the same alias as given above). 

Enter alias of implementation that implements class: myServer 

Class 'classl' now associated with implementation 'myServer' 



The top-level menu will then reappear. Repeat the previous three steps until all classes have been associated with the server. 

Then, from the SAVE & EXIT OPERATIONS section, select "1 1. Save data 1 ' to complete the registration. Finally, select "12. Exit" to exit the 
regimpl utility. 

[ IMPLEMENTATION OPERATIONS ] 

I. Add 2. Delete 3. Change 

4. Show one 5. Show all 6. List aliases 
[ CLASS OPERATIONS ] 

7. Add 8. Delete 9. Delete from all 10. List classes 
[ SAVE & EXIT OPERATIONS ] 

II. Save data 12. Exit 

Enter operation: 11 
Enter operation: 12 



Command line interface to 'regimpl' 



The regimpl utility also has a command line interface. The command flags correspond to the interactive commands described above. The 
syntax of the regimpl commands follow. 

Note: The regimpl command and any optional regimpl command flags can be entered at a system prompt, and the command will execute 
as described below. For OS/2 and Windows users, this et-based interface is particularly useful in batch files. 



To enter interactive mode: 

regimpl 



To add an implementation: 

regimpl -A -i <str> [-p <str>] [-v <str>] [-f <str>] [-b <str>] 

[-h <str>] [-m {on|off}] [-z <str>] [-n {on|off}] 



To update an implementation: 

regimpl -U -i <str> [-p <str>] [-v<str>] [-f <str>] [-b <str>] 

[-h <str>] [-m {on|off}] f-n {on|off}] 




To delete one or more implementations: 

regimpl — D -i <str> [-i ...] 



To list all, or selected, implementations: 

regimpl — L [-i <str> [-i ...]] 

To list all implementation aliases: 

regimpl — S 

To add class associations to one or more implementations: 

regimpl —a -c <str> [-c ...] -i <str> [-i ...rbrk. 

To delete class associations from all, or selected, implementations: 

regimpl -d -c <str> [-c ...][-i <str> [—...]] 

To list classes associated with all, or selected, implementation: 

regimpl —1 [-i <str> [-i ...]] 



The following parameters are used in the commands described above: 



-i <str> 

-p <str> 

-v <str> 

-f <str> 

-b <str> 

-h <str> 

-m {on|off} 
-z <str> 

-c <str> 

-n {on|off} 



Implementation alias name (maximum of 16 -i names) 
Server program name (default: somdsvr) 

Server-class name (default: SOMDServer) 

Reference data file name (optional) 

Reference data backup file name (optional) 

Host machine name (default: localhost) 

Enable multi-threaded server (optional) 
Implementation ID (optional) 

Class name (maximum of 16 -c names) 

Designate the server as nonstoppable (optional) , 
meaning that the server cannot be stopped using 
the SOMDServerMgr interfaces or the "dsom" utility. 



Registration steps using 'pregimpl' or 'wregimpl' 



The pregimpl utility is a Presentation Manager version of regimpl, the DSOM implementation definition utility. Similarly, the wregimpl utility 
is a Windows version of regimpl. The pregimpl and wregimpl utilities offer all the functionality of regimpl except its command-line 
arguments (described earlier in "Command line interface to 'regimpl'"). In addition, the pregimpl and wregimpl utilities provide an intuitive 
GUI interface in place of regimpl's text-based interface. Before proceeding, you should first familiarize yourself with the basic registration 
process described earlier in "Registration steps using 'regimpl'". 

Note: OS/2 or Windows users can execute the text-interface regimpl utility by entering "regimpl" at a system prompt, as described in the 
previous topic, "Command line interface to 'regimpl'." This facility is available primarily for use in batch files. 

You can start the pregimpl or wregimpl utility conveniently in either of two ways: 

• From the Register Impls icon in the SOMobjects icon group, or 

• From the Run option of the File menu. 

With pregimpl or wregimpl, you can view, add, change or delete DSOM implementation definitions, as well as view add or delete 
implementation class definitions. These basic functions are accessible from the main menu in the initial window that displays when you start 
pregimpl or wregimpl. Thus, the main menu offers the choices: 




File 

Implementations 

Classes 

To work with an implementation definition, first click Implementations on the main menu (or press Alt-1). The pulldown menu that appears 
shows the options: 

View 

Add 

Change 

Delete 

To add an implementation definition, click Add on the pulldown menu (or press A). This will bring up the Add Implementations dialog box, 
where you can define or change fields as necessary. The "Alias" field is the only blank field for which a setting is mandatory. For this, you 
should enter a "shorthand" name for conveniently referencing the registered server implementation while using pregimpl or wregimpl; for 
example: myServer 

Except for the "Alias" setting, the remainder of the fields may be left either blank or with the default settings that are provided (see 
"Registration steps using 'regimpl'". for descriptions of the defaults). If you should clear a field that originally contained a default, then when 
the implementation is applied, pregimpl or wregimpl will still use the default setting [Note: The implementation-ID ("Impl ID") field is also 
displayed. This is not an editable field but is shown for information purposes.] 

Once the definition is complete, click Apply (or press Alt-A) to add the definition. Click Discard (or Alt-D) to discard a new definition. You can 
select Exit (or Alt-X) at any time to exit the dialog box. (Message boxes or confirmation windows typically appear after you make entries.) 

To change an implementation definition, click Change from the Implementations pulldown menu (or press C). In the Change 
Implementations dialog box that appears, you can select the desired implementation by scrolling though the list box on the left and 
highlighting your choice. Each time an implementation is highlighted, details of its definition will appear in the edit fields on the right. You can 
change any of the fields except the implementation-ID. Once the changes are made, click Apply (or Alt-A) or Discard (or Alt-D) as desired. 
Click Exit (or Alt-X) to exit the dialog box. 

The View and Delete implementations functions work similarly to the Change Implementations function above. That is, you can highlight a 
selection in the list box on the left, and details of its definition will appear in the edit fields on the right. In the Delete Implementations dialog 
box, click Delete Current Implementation to delete a selected implementation definition. For either function, click Exit (or Alt-X) to exit the 
dialog box. 

To work with class definitions, first click Classes from the main menu (or press Alt-C). This produces a pulldown menu with the options: 

View 

Add 

Delete 

To add classes, select Add on the Classes pulldown menu (or press A) From the resulting Add Classes dialog box, you can select an 
implementation by scrolling through the list box on the left and highlighting your choice. When an implementation is selected, the classes 
associated with it will display in the list box on the right. To add a new class name to the highlighted implementation, enter the name in the 
edit field at the bottom right, and click Add Class (or press Alt-A). The new class name will then appear in the list box on the right. 

The current class name will not be cleared from the edit field, so that more implementations may be selected, if appropriate, and the same 
class can be added to them. Or, you can enter another new class name and add it to the implementation as described above. Exit (or Alt-X) 
may be selected at any time to exit the dialog box. 

To view classes. select View from the Classes pulldown menu (or press V). When you highlight an implementation in the list box on the left, 
the classes associated with the implementation will be shown in the list box on the right. 

To switch key order, select the "Classes" radio button under "Display keyed by". This causes all of the defined classes to appear in the list 
box on the left. When you highlight a class name, all of the implementations associated with that class will appear in the list box on the right. 
Exit (or Alt-X) may be selected at any time to exit the dialog box. 

To delete classes. select Delete from the Classes pulldown menu (or press D). When you highlight an implementation in the list box on the 
left, the classes associated with the implementation will be shown in the list box on the right. You can then highlight a class and click Delete 
Class (or Alt-D) to delete the class from the highlighted implementation. A confirmation window will appear next, which will also give you the 
option of deleting the class from all implementations. Exit (or Alt-X) may be selected at any time to exit the dialog box. 

Important: Please note that any changes are saved internally in memory, but are not written to the database until you save the changes by 
clicking File (or Alt-F) from the main menu and the n Save (or S) from the resulting pulldown menu. Conversely, you can abort all changes 
and reload the original database by clicking File (Alt-F) and then Abort+Reload (A). To exit the pregimpl or wregimpl program, click File 
(Alt-F) and then Exit (X). 



Programmatic interface to the Implementation Repository 




The Implementation Repository can be accessed and updated dynamically using the programmatic interface provided by the 
ImpIRepository class (defined in "implrep.idl"). The global variable SOMDJmpIRepObject is initialized by SOMDJnit to point to the 
ImpIRepositor object. The following methods are defined on it: 



void addimpldef (in ImplementationDef impldef) 



Adds an implementation definition to the Implementation Repository. (Note: The value of the "impljd" attribute is ignored. A 
unique Implld will be generated for the newly added ImplementationDef.) 



void deletej-mpldef (in Implld implid) ; 



Deletes an implementation definition from the Implementation Repository. 



void updateimpldef (in ImplementationDef impldef); 



Updates the implementation definition (defined by the "impljd" of the supplied implementationDef) in the Implementation 
Repository. 



ImplementationDef findimpldef (in Implld implid); 



Returns a server implementation definition given its ID. 



ImplementationDef findimpldef _by_alias ( in string alias_name) ; 



Returns a server implementation definition, given its user-friendly alias. 



sequence< Implement at ionDef > findimpldef J3y__class 

(in string classname) 

Returns a sequence of ImplementationDefs for those servers that have an association with the specified class. Typically, a 
server is associated with the classes it knows how to implement, by registering its known classes via the add_class_toJmpldef 
method. 

ORBStatus find_all_impldef s (out sequence<ImplementationDef > outimpldefs) ; 



Retrieves all ImplementationDef objects in the Implementation Repository. 

The following methods maintain an association between server implementations and the names of the classes they implement. These 
methods effectively maintain a mapping of <className, lmplid>. 



void add_class_to_impldef (in Implld implid, 

in string classname) ; 

Associates a class, identified by name, with a server, identified by its Implld. This type of association is used to lookup server 
implementations via the findjmpldef_by_class method. 




void 



removec 1 a s s_f r om_imp 1 de f 

in 

in 



( 

Implld implid, 
string classname) ; 



Removes the association of a particular class with a server. 



void remove_class_from_all ( 

in string classname) ; 



Removes the association of a particular class from all server implementations in the Implementation Repository. 



sequence<string> f ind_classes_by_impldef 

(in Implld implid) ; 



Returns a sequence of class names associated with a server. 

With the ImpIRepository programmatic interface, it is possible for an application to define additional server implementations at run time. 



The 'dsom' server manager utility 



The dsom utility is a command-line utility program used to manage server processes. At present, server processes that can be managed 
are limited to those present in the Implementation Repository. The choice of Implementation Repository is determined by the environment 
variable SOMDDIR. The dsom utility can be used to start, restart, stop, list, enable, or disable server processes. Note: The dsom command 
requires somdd to be running on the machine in which the server process is (or will be) located. 

The syntax of the dsom command is as follows: 



dsom <cmd> { impl_aliasl [impl_alias2 ...] I -a} 



where <cmd> can be any one of the terms: start, restart, stop, list, disable, or enable. Each imp/_a//as is the server-alias name for a 
server process All forms of the command take one or more server-alias names, or a wild card option -a. The -a will be replaced with all of 
the server-alias names present in the Implementation Repository. 

For example, to start one or more server processes, the command takes the form: 

dsom start { impl_aliasl [impl_alias2 ...] | -a } 



To restart one or more server processes: 

dsom restart { impl_aliasl [impl_alias2 ...] | — a } 



Note: A server registered (using regimpl) as "nonstoppable" cannot be terminated using the "dsom stop" command or its programmatic 
equivalent, SOMDServerMgr::somdShutdownServer. 



To stop one or more server processes: 

dsom stop { impl_aliasl [impl_alias2 ...] | — a } 



Note: A server registered (using regimpl) as "nonstoppable" cannot be terminated using the "dsom stop" command or its programmatic 




equivalent, SOMDServerMgr::somdShutdownServer. 



To list the status of one or more server processes: 

dsom list { impl_aliasl [impl_alias2 ...] | — a } 

To prevent the server processes from starting, use the disable command. To disable one or more server processes: 

dsom disable { impl_aliasl [impl_alias2 ...] | — a } 

A previously disabled server process can be enabled by the enable command. To enable one or more server processes: 

dsom enable { impl_aliasl [impl_alias2 ...] —a } 



Interpretation of 'dsom' messages 



The messages generated by the dsom utility have a one-to-one mapping on the DSOM error codes. Knowing this mapping will aid in a 
better understanding of the dsom return messages. The following six messages are mapped onto the DSOM error code of 0 (success) 



'dsom' cmd 

start 

restart 

list 

stop 

disable 

enable 



Message 

"Started server process** 
"Restarted server process** 
"Server process currently running* 
"Stopped server process** 
"Successfully disabled server" 
"Successfully enabled server" 



The messages generated by the dsom utility commands are mapped onto DSOM error codes, as follows: 



DSOM ERROR CODE 

SOMDERROR_ServerNot Found 

SOMDERROR_NotProcessOwner 

SOMDERROR_NoSocketsClass 

SOMDERROR_NoRemoteComm 

SOMDERROR_CommTimeOut 

SOMDERROR_SendError 

SOMDERROR_SocketSend 

SOMDERROR_Server Inactive 

S OMD E RRO R_N o S OMD I n i t 

SOMDERROR_UnknownError 

SOMDERROR_ServerDisabled 

SOMDERROR_CouldNot St art Process 

SOMDERROR_ServerToBeDeleted 



MESSAGE 

**Server process not running** 

**Cannot stop server; Not process owner** 
**Cannot find Sockets class** 

**Not enabled for Workgroup** 

**Client timed out** 

**Send Error** 

**Send Error** 

**Server activation pending** 

**Unable to create global LocSerOb ject** 

**Command not supported by daemon* 

**Server process is currently disabled** 

**Server process cannot be started** 

**Current server process marked for deletion; 
try again** 




Any other error 



**Request unsuccessful; Unknown error** 



In addition, if the /mp/_a/ias specified with any dsom utility command is not present in the Implementation Repository, DSOM will generate 
the message: "Server alias not found in Implementation Repository**. 

Programmatic interface to manage server processes 

Server processes can also be managed by using the programmatic interface provided by the SOMDServerMgr class. For descriptions of 
the SOMDServerMgr class and its corresponding methods, see the DSOM section of the SOMobjects Developer Toolkit Programmers 
Reference Manual. 



Verifying the DSOM environment with 'somdchk' 



The somdchk program evaluates the environment to verify whether DSOM can operate correctly. As described in the preceding topic s of 
Sections 6.5 "Implementing Classes" and 6.6 "Configuring DSOM Applications," to operate correctly DSOM must be able to find the 
appropriate libraries (DLLs), the Interface Repository, and the Implementation Repository. The settings of various environment variables 
help DSOM find the path to the libraries and repositories. 

The somdchk program generates messages that evaluate the DSOM environment. It determines whether the necessary SOM DLLs can be 
located, whether DSOM is enabled for workgroup (cross-machine) communication, whether Interface and Implementation Repositories can 
be located, and it displays the settings of important environment variables. In its "verbose" mode, somdchk gives the default settings for 
DSOM environment variables and explains how DSOM uses them. 

On AIX or OS/2, the program is invoked from the command line using the syntax given below. The optional verbose setting can be turned on 
by including the -v option with the command: 

somdchk [— v] 



On Windows, the somdchk program can be invoked by double clicking on the SOMDCHK icon. The resulting messages will appear in the 
message window. 

The following example shows sample output from the somdchk -v command on AIX. Output on other platforms would look similar. 

DSOM ENVIRONMENT EVALUATION 
SOMBASE = /usr/lpp/som 

SOMBASE should not be set to the base directory of the SOMObjects Toolkit Enablers. 

Searching for important DLLs 

/usr/lpp/som/lib/som. dll found. 

/usr/lpp/som/lib/somd . dll found. 

/usr/lpp/som/lib/soms . dll found. 

/usr/lpp/ som/lib/ somst .dll found. 

/usr/lpp/som/lib/somd . dll IS Workgroup Enabled. 

Workgroup Enabled DLL permits inter-machine communication. 

SOMSOCKETS = TCPIPSockets 

SOMSOCKETS must be set. Valid settings are: 

TCPIPSockets for TCPIP. 

IPXSockets for NetWare. 

SOMDDIR = /u/raviv/impl_rep/ 

Valid Implementation Repository found in /u/raviv/impl_rep/ 

SOMDDIR may be set to a valid directory in which the Implementation Repository 
resides . 

Default is /usr/lpp/som/etc/dsom 



SOMIR = /u/raviv/raviv . ir 

SOMIR may be set to a list of file names which together form the Interface 
Repository . 

Default is ./som.ir 
/u/raviv/raviv . ir found. 

SOMDPORT = 3001 

SOMDPORT may be set to a 'well-known port'. Default value is 9393. 




SOMDTIMEOUT = (null) . 

SOMDTIMEOUT may be set to the number of seconds to timeout. 
Default value is 600. 



SOMDDEBUG = 2 

SOMDDEBUG may be set to 1 to enable runtime error messages. 
Default value is 0. 



SOMDMESSAGELOG = (null) . 

SOMDMESSAGELOG may be set to the name of a file where messages may be logged. 
Default is stdout . 



Freeing interprocess communication resources on AIX 



DSOM allocates interprocess communication (IPC) resources during execution. Normally, these resources are freed and returned to the 
system when SOMD_Uninit is called. On AIX, however, if a DSOM process terminates without calling SOMD_Uninit, the resources often 
remain allocated. 

DSOM offers two solutions for this problem. Either the somdclean or cleanipc command can be used, as you prefer. 



Using 'somdclean' 



As the first alternative, a DSOM kernel extension can be set up, which automatically frees the system resources used by DSOM when a 
process exits. The somdclean command is issued to load, unload or query a DSOM kernel extension, as follows: 

somdclean -I Loads the kernel extension 

somdclean -u Unloads the kernel extension 

somdclean Queries the current state of the kernel extension 

The somdclean command can only be executed by a privileged user. Hence, you must execute this command as "root". 

The kernel extension is only aware of DSOM processes started after it has been loaded. That is, if a DSOM process is started before the 
kernel extension is loaded, the resources associated with the existing process will not be freed. 

Before you unload the kernel extension, verify that there are no active DSOM processes. If the kernel extension is unloaded while DSOM is 
using it, the system will crash. 



Using 'cleanipc' 



As another alternative, the cleanipc script can be used to free the IPC resources allocated to a particular AIX user, as follows: 
cleanipc [ user/d \ Frees resources for the specified user 

If the user/d parameter is not specified, cleanipc by default uses the environment variable USER. 

The cleanipc script should be run only after all DSOM processes have ended. A limitation of cleanipc is that it is not able to distinguish 
between resources that were created by DSOM and resources created by other products. As a result, cleanipc may affect other 
applications. 



Running DSOM Applications 




Prior to starting the DSOM processes, the DSOM executables should be installed and the DSOM environment variables should be set 
appropriately, as discussed in the earlier section, "Configuring DSOM Applications.” 



Running the DSOM daemon (somdd) 

To run a DSOM application, the DSOM daemon, somdd, must be started: 

• On AIX or OS/2, the daemon can be started manually from the command line, or could be started automatically from a start-up 
script run at boot time. It may be run in the background with the commands somdd& on AIX, and start somdd on OS/2. 
(Thesomdd command has the following syntax: 

somdd [-q] 



where the optional -q flag signifies "quiet" mode. By default, somdd will produce a" ready" message when the DSOM daemon is 
ready to process requests, and it will produce diagnostic messages as errors are encountered if the SOMDDEBUG environment 
variable is set to 1 . In quiet mode, however, the "ready" message will not appear, and diagnostic messages will not appear even 
if SOMDEBUG is set. Alternatively, if the SOMDMESSAGELOG environment variable is set, diagnostic error messages will be 
sent directly to the specified message log file, regardless of whether the -q flag is specified. 

• On Windows, the daemon can be started with the DSOM Daemon icon in the SOM icon group or started in Windows from the 
Run option of the file menu. The DSOM Daemon icon will change colors to indicate that the daemon is ready, after which client 
and server programs can be started. 

The somdd daemon is responsible for "binding" a client process to a server process and will activate the desired server if necessary. The 
binding procedure is such that the client will consult the Implementation Repository to find out which machine contains a desired server, and 
will then contact the DSOM daemon on the server's machine to retrieve the server's communications address (a port). Servers are activated 
dynamically as separate processes. 



Running DSOM servers 



Once the somdd daemon is running, application programs can be started. If the application uses the generic SOM server, somdsvr, it can 
be started either from the command line or automatically upon demand. When starting somdsvr from the command line, the server's 
implementation ID or alias must be supplied as an argument. The command syntax for starting a generic SOM server is: 

somdsvr [ impl_id | -a alias ] 

For example, the command 

$ somdsvr 2ad2 688fb-0038 9c00-7 f-00-10005ac900d8 

would start a somdsvr for an implementation with the specified ID. Likewise, the command 

$ somdsvr -a myServer 

would start a somdsvr that represents an implementation of "myServer". 

Servers can also be started from the command line using the "dsom start" command: 

dsom start {impl_aliasl [impl_alias2 ...] I -a} 

or programmatically using the somdStartServer method of the SOMDServerMgr class. See the section entitled "The 'dsom' server 
manager utility" for more information on the dsom command-line utility. See the DSOM section of the SOMobjects Deve/oper Too/kit 
Programmers Reference manual for a description of the SOMDServerMgr class and its methods. 




DSOM as a CORBA-compliant Object Request Broker 



The Object Management Group (OMG) consortium defines the notion of an Object Request Broker (ORB) that supports access to remote 
objects in a distributed environment. Thus, Distributed SOM is an ORB. SOM and DSOM together comply with the OMG's specification of 
the Common Object Request Broker Architecture (CORBA). 

Since the interfaces of SOM and DSOM are largely determined by the CORBA specification, the CORBA components and interfaces are 
highlighted in this section. 

The CORBA specification defines the components and interfaces that must be present in an ORB, including the: 

• Interface Definition Language (IDL) for defining classes (discussed in Chapter 4, "SOM IDL and the SOM Compiler"). 

• C usage bindings (procedure-call formats) for invoking methods on remote objects, 

• Dynamic Invocation Interface and an Interface Repository, which support the construction of requests (method calls) at run time 
(for example, for interactive desktop applications), and 

• Object Request Broker run-time programming interfaces. 

SOM and DSOM were developed to comply with these specifications (with only minor extensions to take advantage of SOM services). 
Although the capabilities of SOM are integral to the implementation of DSOM, the application programmer need not be aware of SOM as the 
implementation technology for the ORB. 

This section assumes some familiarity with The Common Object Request Broker: Architecture and Specification, Revision /. / jaiso referred 
to as "CORBA /. ij. The specification is published jointly by the Object Management Group and x/Open. The mapping of some CORBA 1.1 
terms and concepts to D SOM terms and concepts is described in the remainder of this section. 



Mapping OMG CORBA terminology onto DSOM 

This section discusses how various CORBA concepts and terms are defined in terms of DSOM's implementation of the CORBA 1 .1 
standard. 



Object Request Broker run-time interfaces 



In the previous sections, the SOMDObjectMgr and SOMDServer classes were introduced. These are classes defined by DSOM to provide 
basic support in managing objects in a distributed application. These classes are built upon Object Request Broker interfaces defined by 
CORBA for building and dispatching requests on objects. The ORB interfaces, SOMDObjectMgr and SOMDServer, together provide the 
support for implementing distributed applications in DSOM. 

CORBA 1.1 defines the interfaces to the ORB components in IDL. In DSOM, the ORB components are implemented as SOM classes whose 
interfaces are expressed using the same CORBA 1.1 IDL. Thus, an application can make calls to the DSOM run time using the SOM 
language bindings of its choice. 

Interfaces for the following ORB run-time components are defined in CORBA 1.1, and are implemented in DSOM. They are introduced 
briefly here, and discussed in more detail throughout this chapter. (See the SOMobjects Deve/oper Too/kit: Programmers Reference Manuai 
for the complete interface definitions.) 

Object The Object interface defines operations on an "object reference", which is the information 

needed to specify an object within the ORB. 

In DSOM, the class SOMDObject implements the CORBA 1 .1 Object interface. 
(The"SOMD" prefix was added to distinguish this class from SOMObject.) The subclass 
SOMDClientProxy extends SOMDObject with support for proxy objects. 

ORB (Object Request Broker) The ORB interface defines utility routines for building requests and 

saving references to distributed objects. The global variable SOMD_ORBObject is 
initialized by SOMDJnit and provides the reference to the ORB object. 




ImplementationDef An ImplementationDef object is used to describe an object's implementation. Typically, the 

ImplementationDef describes the program that implements an object's server, how the 
program is activated, and so on. 

(CORBA 1.1 introduces ImplementationDef as the name of the interface, but leaves the 
remainder of the IDL specification to the particular ORB. DSOM defines an interface for 

ImplementationDef.) 

ImplementationDef objects are stored in the Implementation Repository (defined in DSOM 

by the ImpIRepository class). 

InterfaceDef An InterfaceDef object is used to describe an IDL interface in a manner that can be queried 

and manipulated at run time when building requests dynamically, for example. 

InterfaceDef objects are stored in the Interface Repository (described fully in Chapter 7, 
"The Interface Repository Framework"). 

Request A Request object represents a specific request on an object, constructed at run-time. The 

Request object contains the target object reference, operation (method) name, a list of 
input and output arguments. A Request can be invoked synchronously (wait for the 
response), asynchronously (initiate the call, and later, get the response), or as a "oneway" 
call (no response expected). 

NVList An NVList is a list of NamedValue structures, used primarily in building Request objects. A 

NamedValue structure consists of a name, typed value, and some flags indicating how to 
interpret the value, how to allocate/free the value's memory, and so on. 

Context A Context object contains a list of "properties" that represent information about an 

application process's environment. Each Context property consists of a 
<name,string_value> pair, and is used by application programs or methods much like the 
"environment variables" commonly found in operating systems like AIX and OS/2 and 
Windows. IDL method interfaces can explicitly list which properties are queried by a 
method, and the ORB will pass those property values to a remote target object when 
making a request. 

Principal A Principal object identifies the principal ("user”) on whose behalf a request is being 

performed. 

(CORBA 1.1 introduces the name of the interface, Principal, but leaves the remainder of 
the IDL specification to the particular ORB. DSOM defines an interface for Principal.) 

BOA (Basic Object Adapter) An Object Adapter provides the primary interface between an 

implementation and the ORB "core". An ORB may have a number of Object Adapters, with 
interfaces that are appropriate for specific kinds of objects. 

The Basic Object Adapter is intended to be a general-purpose Object Adapter available on all CORBA-compliant Object Request Brokers. 
The BOA interface provides support for generation of object references, identification of the principal making a call, activation and 
deactivation of objects and implementations, and method invocation on objects. 

In DSOM, BOA is defined as an abstract class. The SOMOA (SOM Object Adapter) class, derived from BOA, is DSOM's primary Object 
Adapter implementation. The SOMOA interface extends the BOA interface with several of its own methods that are not defined by CORBA 
1 . 1 . 



Object references and proxy objects 



CORBA 1.1 defines the notion of an object reference , which is the information needed to specify an object in the ORB. An object is defined 
by its ImplementationDef, InterfaceDef, and application-specific "reference data" used to identify or describe the object. An object 
reference is used as a handle to a remote object in method calls. When a server wants to export a reference to an object it implements, it 
supplies the object's ImplementationDef, InterfaceDef, and reference data to the Object Adapter, which returns the reference. 

The structure of an object reference is opaque to the application, leaving its representation up to the ORB. 

In DSOM, an object reference is represented as an object that can simply be used to identify the object on that server. The DSOM class that 
implements simple object references is called SOMDObject (corresponding to Object in CORBA 1.1.) Flowever, in a client's address space, 
DSOM represents the remote object with a proxy object in order to allow the client to invoke methods on the target object as if it were local. 
When an object reference is passed from a server to a client, DSOM dynamica/ty and automat/ca/ty creates a proxy in the client for the 




remote object. Proxies are specialized forms of SOMDObject; accordingly, the base proxy class in DSOM SOMDClientProxy, is derived 
from SOMDObject. 

In order to create a proxy object, DSOM must first build a proxy class. It does so automatically using SOM facilities for building classes at 
run time. The proxy class is constructed using multiple inheritance: the proxy object functionality is inherited from SOMDClientProxy, while 
just the interface of the target class is inherited. 

In the newly derived proxy class, DSOM overrides each method inherited from the target class with a "remote dispatch" method that 
forwards an invocation request to the remote object. Consequently, the proxy object provides location transparency, and the client code 
invokes operations (methods) on the remote object using the same language bindings as if it were a local target object. 

For example, recall the "Stack" class used in the tutorial example given earlier. When a server returns a reference to a remote "Stack" object 

to the client, DSOM builds a "Stack Proxy" class (note two underscores in the name), derived from SOMDClientProxy and "Stack", and 

creates a proxy object from that class. When the client invokes the "push” method on the proxy, 



_push(stk, Sev, 100); 



the method is redispatched using the remote-dispatch method of the SOMDClientProxy class, and the method is forwarded to the target 
object. 

CORBA defines several special operations on object references that operate on the local references (proxies) themselves, rather than on 
the remote objects. These operations are defined by the classes SOMOA (SOM Object Adapter), SOMDObject (which is DSOM's 
implementation of CORBA's Object "pseudo-class" and ORB (Object Request Broker class). Some of these operations are listed below, 
expressed in terms of their IDL definitions. 

SOMOA methods (inherited from BOA): 



sequence <octet,1024> ReferenceData; 

SOMDObject create (in ReferenceData id, in InterfaceDef 
in ImplementationDef impl) ; 



intf 



Creates and returns an object reference. 

SOMDObject methods: 

SOMDObject duplicate ( ) ; 

Creates and returns a duplicate object reference. 

void release ( ) ; 

Destroys an object reference. 

boolean is nil ( ) ; 

Tests to see if the object reference is NULL. 

ORB methods: 



string ob ject_to„string ( SOMDObject obj ) ; 



Converts an object reference to a (storable) string form. 




SOMDObject string__to_ob ject ( string str ) ; 

Converts a string form back to the original object reference. 



Creation of remote objects 



The OMG has standardized an "object lifecycle service,” built on top of the ORB, for creating and destroying remote objects. Currently, 
DSOM provides its own interface for creating and destroying objects (see "Basic Client Programming"), but a future release may provide an 
OMG-compliant lifecycle service as well. 



Interface definition language 



The CORBA specification defines an Interface Definition Language, IDL, for defining object interfaces. The SOM Compiler compiles 
standard IDL interface specifications, but it also allows the class implementer to include implementation information that will be used in the 
implementation bindings for a particular language. 

Note: Before IDL, SOM (version 1.0) had its own Object Interface Definition Language (OIDL). SOM classes specified using OIDL must be 
converted to IDL before they can be used with DSOM. The SOMobjects Developer Toolkit provides a migration tool for this purpose. 



C language mapping 



The CORBA specification defines the mapping of method interface definitions to C language procedure prototypes, hence SOM defines the 
same mapping. This mapping requires passing a reference to the target object and a reference to an implementation-specific Environment 
structure as the first and second parameters, respectively, in any method call. 

The Environment structure is primarily used for passing error information from a method back to its caller. See also the topic "Exceptions 
and Error Handling" in Chapter 3, "Using SOM Classes in Client Programs," for a description of how to "get" and "set" error information in 
the Environment structure. 



Dynamic Invocation Interface (Dll) 



The CORBA specification defines a Dynamic Invocation interface (Dll) that can be used to dynamically build requests on remote objects. 
This interface is described in section 6 (page 105) of the CORBA 1.1 document, and is implemented in DSOM. The DSOM implementation 
of the Dll is described later in this chapter, in the topic entitled "Dynamic Invocation Interface" under Section 6.9 "Advanced topics." Note 
that, in DSOM, somDispatch is overridden so that method invocations on proxy objects are forwarded to the remote target object. SOM 
applications can use the SOM somDispatch method for dynamic method calls whether the object is local or remote. 



Implementations and servers 



The CORBA specification defines the term /mp/ementat/on as the code that implements an object. The implementation usually consists of a 




program and class libraries. 



Serzers are processes that execute object implementations. CORBA 1.1 defines four activation policies for server implementations: shared, 
unshared, server-per-method, and persistent, as follows. 

• A shared server implements multiple objects (of arbitrary classes the same time, and allows multiple methods to be invoked at 
the same time. 

• An unshared server, conversely, implements only a single object and handles one request at a time. 

• The server-per-method policy requires a separate process to be created for each request on an object and, usually, a separate 
program implements each method. 

Under the shared, unshared, and server-per-method activation policies, servers are activated automatically (on demand). 

• A persistent server, by contrast, is a shared server that is activated "by hand" (for example, from the command shell or from a 
startup script), vs. being activated automatically when the first method is dispatched to it. 

The term "persistent server" refers to the relative lifetime of the server: it is "always running" when DSOM is running. (CORBA implies that 
persistent servers are usually started at ORB boot time.) It should not be assumed, however, that a "persistent" server necessarily 
implements persistent objects (that persist between ORB reboots). 

In DSOM, specific process models are implemented bv the server program. That is, DSOM simply starts a specified program when a client 
attempts to connect to a server. The four CORBA activation policies, or any other policies, can be implemented by the application as 
necessary. For example, 

• an object that requires a server-per-method implementation could itself spawn a process at the beginning of each method 
execution. Alternatively, the server object in the "main" server can spawn a process before each method dispatch. 

• a dedicated server could be registered for each object that requires an unshared server implementation (separate process). This 
may be done dynamically (see the topic "Programmatic interface to the Implementation Repository" earlier in this chapter). 

An ImplementationDef object, as defined by the CORBA specification, describes the characteristics of a particular implementation. In 
DSOM, an ImplementationDef identifies an implementation's unique ID, the program name, its location, and so forth. The 
ImplementationDef objects are stored in an /mp/ementat/on Repository, which is represented in DSOM by an ImpIRepository object. 

A CORBA-compliant ORB must provide the mechanisms for a server program to register itself with the ORB. To "register itself with the 
ORB" simply means to tell the ORB enough information about the server process so that the ORB will be able to locate, activate, deactivate, 
and dispatch methods to the server process. DSOM supports these mechanisms, so that server programs written in arbitrary languages can 
be used with DSOM. (See also the next topic, "Object Adapters.") 

In addition to the generic registration mechanisms provided by all CORBA-compliant ORBs, DSOM provides extra support for using 
SOM-class DLLs. DSOM provides a generic server program that automatically registers itself with DSOM, loads SOM-class DLLs on 
demand, and dispatches incoming requests on SOM objects. Thus, by using the generic server program (when appropriate), a user may be 
able to avoid writing any server program code. 



Object Adapters 



An Object Adapter (OA) provides the mechanisms that a server process uses to interact with DSOM, and vice versa. That is, an Object 
Adapter is responsible for server activation and deactivation, dispatching methods, activation and deactivation of individual objects, and 
providing the interface for authentication of the principal making a call. 

DSOM defines a Basic Object Adapter (BOA) interface, described in the CORBA specification, as an abstract class (a class having no 
implementation, only an interface specification). The BOA interface represents generic Object Adapter methods that a server written in an 
arbitrary language can use to register itself and its objects with the ORB. Because it is an abstract class having no implementation, however, 
the BOA class should not be directly instantiated. 

DSOM provides a SOM Object Adapter, SOMOA, derived from the BOA interface, that uses SOM Compiler and run-time support to 
accomplish dispatching of methods (that is, accepting messages, turning them into method invocations, and routing the invocations to the 
target object in the server process). SOMOA can be used to dispatch methods on either SOM or non-SOM object implementations, as 
described in the sections "Implementing Classes" and "Basic Server Programming." It is possible to use non-SOM based implementations 
with SOMOA, and often there is no additional programming required to use implementations (class libraries) already developed using SOM. 

The SOMOA works in conjunction with the application-defined server object to map between objects and object references, and to dispatch 
methods on objects. By partitioning out these mapping and dispatching functions into the server object, the application can more easily 
customize them, without having to build object adapter subclasses. 




SOMOA introduces two methods that handle execution of requests received by the server: 



execute_request_loop 
execute_next_req uest 

Typically, execute_request_loop is used to receive and execute requests, continuously, in the server's main thread. The 
execute_next_request method allows a single request to be executed. Both methods have a non-blocking option: when there are no 
messages pending, the method call will return instead of wait. 

On OS/2, if the server implementation has been registered as "multi-threaded" (via an IMPLDEF_MULTI_THREAD flag in the 
ImplementationDef), SOMOA will automatically run each request in a separate thread. If the "multi-thread" flag is not set, the server 
implementation can still choose to manage its own threads. 

The generic server program provided by DSOM (described in the preceding topic) uses execute_request_loop to receive and execute 
requests on SOM objects. 



Extensions and limitations 



The DSOM implementation has the following extensions and limitations in its implementation of the CORBA specification: 

• As just described, the current release of DSOM supports a simple server activation policy, which is equivalent to the "shared" 
and "persistent" policies defined by CORBA. DSOM does not explicitly support the "unshared" or "server-per-method" server 
activation policies. Policies other than the basic activation scheme must be implemented by the application. 

• DSOM provides null implementations for the object_is_ready or deactivate_obj methods, defined by the BOA interface for the 
unshared server activation policy. 

• DSOM does not support the changejmplementation method, defined by the BOAinterface to allow an application to change 
the implementation definition associated with an object. In DSOM, the ImplementationDef identifies the server which 
implements an object. In these terms, changing an object's ImplementationDef would result in a change in the object's server 
ID. Any existing object references that have the old server ID would be rendered invalid. 

It is possible, however, to change the program which implements an object's server, or change the class library which 
implements an object's class. To modify the program associated with an ImplementationDef, use the updatejmpldef method 
defined on ImpIRepository. To change the implementation of an object's class, replace the corresponding class library with a 
new (upward-compatible) one. 

• The OUT_list_MEMORY, IN_COPY_VALUE, and DEPENDENTJJST flags, used with the Dynamic Invocation Interface, are not 
yet supported. 

• The SOM Object Adapter (SOMOA) provides a method (changejd) to update the ReferenceData associated with an object 
reference created by the create call This is useful if the information which describes the object must be changed without 
invalidating copies of the existing object reference. CORBA defines no such method: changejd is an extension to the standard 
BOA methods. 

• The SOMOA provides some specialized object reference types which, in certain situations, are more efficient or easier-to-use 
than standard object references. 

• DSOM supports the SOM extension to IDL that allows method parameters that are pointers. Structure, sequence, and array 
parameters may only contain pointers to objects (not arbitrary types). 

• The Context::get_values method currently does not support the CTX_RESTRICT_SCOPE flag. 



Advanced Topics 



The following subjects are discussed in this section: 

• Peer vs. client/server processes 

• Dynamic Invocation Interface 

• Creating user-supplied proxies 




Customizing the default base proxy class 
Sockets class 



Peer vs. client/server processes 



The client/server model of distributed computing is appropriate when it is convenient (or necessary) to centralize the implementation and 
management of a set of shared objects in one or more servers. However, some applications require more flexibility in the distribution of 
objects among processes. Specifically, it is often useful to allow processes to manage and export some of their objects, as well as access 
remote objects owned by other processes. In these cases, the application processes do not adhere to a strict client/server relationship; 
instead, they cooperate as "peers", behaving both as clients and as servers. 

Peer applications must be written to respond to incoming asynchronous requests, in addition to performing their normal processing. In a 
multi-threaded system (like OS/2), this is best accomplished by dedicating a separate process thread that handles DSOM communications 
and dispatching. In systems that do not currently support multi-threading (like AIX), peer applications must be structured as event-driven 
programs. 



Multi-threaded DSOM programs 



In a system that supports multi-threading, like OS/2, the easiest way to write a peer DSOM program is to dedicate a separate thread to 
perform the usual "server" processing. This body of this thread would contain the same code as the simple servers described in section 6.4, 
"Basic Server Programming." 

DSOM_thread (void *params) 

{ 

Environment ev; 

SOM_InitEnvironment (&ev) ; 

/* Initialize the DSOM run-time environment */ 

SOMD_Init (&ev) ; 

/* Retrieve its ImplementationDef from the Implementation 
Repository by passing its implementation ID as a key */ 

SOMD_ImplDefOb ject = 

_f ind_impldef (SOMD_ImplRepOb ject , &ev, *(lmplld *)params) ; 

/* Create SOM Object Adapter and begin executing requests */ 

S OMD_S OMO AOb ject = SOMOANewO; 

_impl_is_ready (SOMD_SOMOAOb ject , &ev, SOMD_ImplDefOb ject ) ; 

_execute_request_loop (SOMD_SOMOAOb ject , &ev, SOMD_WAIT) ; 

} 



Note: The DSOM run time is "thread safe"; that is, DSOM protects its own data structures and objects from race conditions and update 
conflicts. However, it is the application's responsibility to implement its own concurrency control for concurrent thread access to local 
shared application objects. 



Event-driven DSOM programs using EMan 



EMan (see Chapter 9 on "The Event Management Framework") is not a replacement for threads, but it supports processing of asynchronous 
requests. EMan allows a program to handle events from multiple input sources; but the handlers run on a single thread, under control of 
EMan's main loop. 

DSOM provides a runtime function, SOMD_RegisterCallback, which is used by DSOM to associate user-supplied event handlers with 
DSOM's communications sockets and message queues with EMan. Example code is shown below. 




DSOM server programs which use EMan must be very careful not to get into deadlock situations. This is quite easy to do with DSOM, since 
method calls are synchronous. If two cooperating processes simultaneously make calls on each other, a deadlock could result. Likewise, if a 
method call on remote object B from A requires a method call back to A, a deadlock cycle will exist. (Of course, the number of processes 
and objects which create the cyclic dependency could be greater than two.) 

The application developer must be careful to avoid situations where cooperating processes are likely to make calls upon each other, 
creating a cyclic dependency. Some applications may find it appropriate to use oneway messages to avoid deadlock cycles, since oneway 
messages do not cause a process to block. It may also be possible for an application to defer the actual processing of a method that may 
"call back' 1 an originating process, by scheduling work using EMan client events. 



Sample server using EMan 



The following server code has been distilled from one of the DSOM sample applications provided with SOMobjects Developer Toolkit, it is 
an example of a server which has an interval timer that signals another server (via DSOM) whenever its timer "pops". Thus, it is both a client 
(of the server it signals) and a server (because it can receive timer notifications from other servers). 

The IDL for the server object class to be used by this server program is as follows. Note that the "noteTimeout" method is oneway, in order 
to avoid deadlock. 

interface PeerServer : SOMDServer 

{ oneway void noteTimeout (in string serverName) ; 

// Notification that a timer event occurred in server serverName 

}; 



The example server program is outlined as follows. It is assumed that "eman.h" has been included by the program. 
• Perform DSOM initialization up to, but not including, asking SOMOA to start handling requests. 

MyEMan = SOMEEManNew ( ) ; 

SOM_InitEnvironment (&ev) ; 

SOM_InitEnvironment (&peerEv) ; 

SOMD_Init (&ev) ; 

somPrintf ( "What is the alias for this server? "); 
gets (thisServer) ; 

SOMD_ImplDefOb ject = _f ind_impldef_by_alias (SOMD_ImplRepOb ject , 

&ev, thisServer) ; 

SOMD_SOMOAOb ject = SOMOANewO; 

_impl_is_ready (SOMD_SOMOAOb ject , &ev, SOMD_ImplDefOb ject ) ; 



Register a "DSOM event" with EMan, having EMan callback to a procedure that asks the SOMOA to process any pending 
DSOM requests. 

void SOMD_RegisterCallback (SOMEEman emanObj, EMRegProc *func) ; 

void DSOMEventCallBack (SOMEEvent event, void *eventData) 

{ Environment ev; 

SOM_InitEnvironment (&ev) ; 

_execute_request_loop (SOMD_SOMOAOb ject , &ev, SOMD_NO_WAIT) ; 

} 



SOMD_RegisterCallback (MyEMan, DSOMEventCallBack) ; 



Ask user to provide "target server's alias", where the target server is that this server will signal when its timer "pops". Then get a 
proxy for that server. 

somPrintf ( "What is the alias for the target server? "); 
gets (inbuf ) ; 

RemotePeer = _somdFindServerByName (SOMD_Ob jectMgr , &ev, inbuf); 



Ask user to provide the timer's interval (in milliseconds) 

somPrintf ( "What is the timer interval, in milliseconds? "); 
gets (inbuf) ; 




Interval = atoi(inbuf); 



Register a timer event with EMan, having EMan call back a procedure that will invoke the notification method on the target 
server. 

void TimerEventCallBack (SOMEEvent event, void *eventData) 

{ Environment ev; 

SOM_InitEnvironment (&ev) ; 

/* call the peer, with a oneway message */ 

_noteTimeout (RemotePeer, &ev, thisServer) ; 



data = SOMEEMRegisterDataNew ( ) ; 

_someClearRegData (data, &ev) ; 

_someSetRegDataEventMask (data, &ev, EMTimerEvent , NULL); 
_someSetRegDataTimerInterval (data, &ev, Interval); 
somPrintf ( "Type <Enter> key when ready to go: "); 
gets (inbuf ) ; 

regld = _someRegisterProc (MyEMan, &ev, data, TimerEventCallBack, 

NULL) ; 



Important Do not use someRegister or someRegisterEV to register "callback methods" that would be executed on proxy 

objects. Instead, write a callback routine that invokes the desired method on the proxy, like the one shown above, and 
register that routine using the method someRegisterProc. 

Note: EMan currently uses the methods someRegister and someRegisterEv to obtain the address of a method-procedure to 
call when a specified event occurs. If EMan directly calls the method-procedure versus somDispatch, the method call will 
not be forwarded to the remote object as desired. 

Start the EMan event processing loop. 

_someProcessEvents (MyEMan, &ev) ; 



Before the sample is run, two server implementations should be registered with regimpl. The implementations are identical except for their 
aliases. One may be called "peerServerl " and the other "peerServer2”. The "PeerServer" class should be specified as their server-object 
class. 

Whenever peerServerl 's timer pops, the Event Manager causes a method, "noteTimeout", to be sent to the server object in peerServer2. 
PeerServer2's server object executes this method by displaying a message on its window. Whenever peerServer2's timer pops, a similar 
sequence occurs with peerServerl . The two servers will run continuously until interrupted. 



Dynamic Invocation Interface 



DSOM supports the CORBA dynamic invocation interface (Dll), which clients can use to dynamically build and invoke requests on objects. 
This section describes how to use the DSOM Dll. Currently, DSOM supports dynamic request invocation only on objects outside the 
address space of the request initiator, via proxies. The somDispatch method (non-CORBA) can be used to invoke methods dynamically on 
either local or remote objects, however. 

To invoke a request on an object using the Dll, the client must explicitly construct and initiate the request. A request is comprised of an 
object reference, an operation, a list of arguments for the operation, and a return value from the operation. A key to proper construction of 
the request is the correct usage of the NamedValue structure and the NVList object. The return value for an operation is supplied to the 
request in the form of a NamedValue structure. In addition, it is usually most convenient to supply the arguments for a request in the form of 
an NVList object, which is an ordered set of NamedValues. This section begins with a description of NamedValues and NVLists and then 
details the procedure for building and initiating requests. 



The NamedValue structure 



The NamedValue structure is defined in C as: 




typedef unsigned long Flags; 



struct NamedValue { 
Identifier 
any 
long 
Flags 

} ; 



name ; 
argument ; 
len; 

arg_modes; 



/ / argument name 
// argument 

// length/count of arg value 
// argument mode flags 



where: name is an Identifier string as defined in the CORBA specification, and argument is an any structure with the following declaration: 



struct any { 

TypeCode 

void* 

} ; 



-type; 

_value; 



_type is a TypeCode, which has an opaque representation with operations defined on it to allow access to its constituent parts. Essentially 
the Typecode is composed of a field specifying the CORBA type represented and possibly additional fields needed to fully describe the 
type. See Chapter 7 of this manual for a complete explanation of TypeCodes. 

_ va/ue is a pointer to the value of the any structure, important.- The contents of "_value" should always be a pointer to the value, 
regardless of whether the value is a primitive, a structure, or is itself a pointer (as in the case of object references, strings and arrays). For 
object references, strings and arrays. _value should contain pointer to the pointer that references the value. For example: 



string teststring; 

any testAny; 

testAny ._value = &testString; 



ien is the number of bytes that the argument value occupies. The following table gives the length of data values for the C language 
bindings. The value of ien must be consistent with the TypeCode. 



Data type 
short 

unsigned short 
long 

unsigned long 

float 

double 

char 

boolean 

octet 

string 

enum E { } 

union U 

struct S { } 

Object 

array N of type T1 
sequence V of type T2 



Length 

sizeof (short) 

sizeof (unsigned short) 

sizeof (long) 

sizeof (unsigned long) 

sizeof (float) 

sizeof (double) 

sizeof (char) 

sizeof (boolean) 

sizeof (octet) 

strlen (string) - does not include ' \ 0 ' byte 
sizeof (unsigned long) 
sizeof (U) 
sizeof (S) 

1 

Length (Tl) *N 

Length (T2)*V - V is the actual # of elements 



The arg_modes field is a bitmask (unsigned long) and may contain the following flag values: 



ARG_IN 


the 


ARG_OUT 


the 


ARG_INOUT 


the 



associated value is 
associated value is 
associated argument 



an input-only argument 
an output-only argument 
is an in/out argument 



These flag values identify the parameter passing mode for the arguments. Additional flag values have specific meanings for Request and 
NVList methods and are listed with their associated methods. 



The NVList class 



An NVList contains an ordered set of NamedValues. The CORBA specification defines several operations that the NVList supports. The 




IDL prototypes for these methods are as follows: 



// get the number of elements in the NVList 
ORBStatus get_count ( 

out long count ) ; 

// add an element to an NVList 
ORBStatus add_item( 

in Identifier item_name, 

in TypeCode item_type, 
in void* value, 
in Flags item_flags ) ; 

// frees the NVList and any associated memory 
ORBStatus free ( ) ; 



// frees dynamically allocated memory associated with the list 
ORBStatus free_memory ( ) ; 



In DSOM, the NVList is a full-fledged object with methods for getting and setting elements: 



in an NVList 



//set the contents of an element 
ORBStatus set_item ( 



in 


long 


in 


Identifier 


in 


TypeCode 


in 


void* 


in 


long 


in 


Flags 



// get the contents 
ORBStatus get_item ( 


of an element 


in 


long 


out 


Identifier 


out 


TypeCode 


out 


void* 


out 


long 


out 


Flags 



item_number, /* element # to set */ 

item_name, 

item_type, 

item_value, 

value_len, 

item_flags ) ; 



item_number, /* element # to get */ 

item_name, 

item_type, 

item_value, 

value_len, 

item_flags ) ; 



in an NVList 



Creating argument lists 



A very important use of the NVList is to pass the argument list for an operation when creating a request. CORBA 1.1 specifies two methods, 
defined in the ORB class, to build an argument list: createjist and create_operation_list. The IDL prototypes for these methods are as 
follows: 

ORBStatus createjist ( 

in long count, /* # of items */ 

out NVList new_list ) ; 

ORBStatus create_operation _list ( 

in OperationDef oper, 

out NVList new_list ) ; 



The createjist method returns an NVList with the specified number of elements. Each of the elements is empty. It is the client's 
responsibility to fill the elements in the list with the correct information using the setjtem method. Elements in the NVList must contain the 
arguments in the same order as they were defined for the operation. Elements are numbered from 0 to count-1 . 

The create_operationJist method returns an NVList initialized with the argument descriptions for a given operation (specified by the 
OperationDef). The arguments are returned in the same order as they were defined for the operation. The client only needs to fill in the 
/tern va/ue and va/ue ten in the elemens of the NVList. 




In addition to these CORBA-defined methods, DSOM provides a third version, defined in the SOMDObject class. The IDL prototype for this 
method is as follows: 



ORBStatus create request args ( 

in Identifier operation, 
out NVList arg_list, 
out NamedValue result ) ; 



Like create_operation_list, the create_request_args method creates the appropriate NVList for the specified operation. In addition, 
create_request_args initializes the NamedValue that will hold the result with the expected return type. The create_request_args method 
is defined as a companion to the create_request method, and has the advantage that the InterfaceDef for the operation does not have to 
be retrieved from the Interface Repository. 

Note: The create_request_args method is not defined in CORBA 1.1. Hence, the create_operation_list method, defined on the ORB 
class, should be used instead when writing portable CORBA-compliant programs. 



Building a Request 



There are two ways to build a Request object. Both begin by calling the create_request method defined by the SOMDObject class. The 
IDL prototype for create_request is as follows: 



ORBStatus create_request ( 

in Context 
in Identifier 
in NVList 
inout NamedValue 
out Request 
in Flags 



ctx, 

operation, 
arg_list , 
result, 
request, 
req_flags ) ; 



The arg_//st can be constructed using the procedures described above and is passed to the Request object in the create_request call. 
Alternatively, argjist can be specified as NULL and repetitive calls to add_arg can be used to specify the argument list. The add_arg 
method, defined by the Request class, has the following IDL prototype: 



ORBStatus add_arg ( 
in 
in 
in 
in 
in 



Identifier 

TypeCode 

void* 

long 

Flags 



name, 

arg_type, 

value, 

len, 

arg_flags ) ; 



Initiating a Request 



There are two ways to initiate a request, using either the invoke or send method defined by the Request class. The IDL prototypes for 
these two operations ar as follows: 



ORBStatus invoke ( 

in Flags invoke_flags ) ; 

ORBStatus send ( 

in Flags send_flags ) ; 



The invoke method calls the ORB, which handles the remote method invocation and returns the result. This method will block while awaiting 




return of the result. 



The send method calls the ORB but does not wait for the operation to complete before returning. To determine when the operation is 
complete, the client must call the get_response method (also defined by the Request class), which has this IDL prototype: 



ORBStatus get_response ( 

in Flags response_f lags ) ; 



The following flag is defined for get_response: 

RESP_NO_WAIT Means that the caller does not want to wait for a 
response. 

get_response determines whether a request has competed. If the RESP_NO_WAIT flag is set, get_response returns immediately even if 
the request is still in progress. If RESP_NO_WAIT is not set, get_response waits until the request is done before returning. 



Example code 



Following is an incomplete example showing how to use the Dll to invoke a request having the method procedure prototype shown here: 



string _testMethod ( testObject 
Environment 
long 

) ; 



ob j , 

*ev, 

input_value, 



main ( ) 

{ 

ORBStatus rc; 

Environment ev; 

SOMDObject obj; 

NVList arglist; 

NamedValue result; 

Context ctx; 

Request reqObj; 

OperationDef opdef; 

Description desc; 

OperationDescription opdesc; 
static long input_value = 999; 

SOM_InitEnvironment (Sev) ; 

SOMD_Init (Sev) ; 

/* create the argument list */ 

/* get the operation description from the interface repository */ 
opdef = _lookup_id (SOM_InterfaceRepository, *ev, 

"testObject : : testMethod" ) ; 
desc = _describe (opdef , Sev); 

opdesc = (OperationDescription *) desc .value ._value; 

/* fill in the TypeCode field for the result */ 
result . argument ._type = opdesc->result ; 

/* Initialize the argument list */ 

rc = _create_operation_list (SOMD_ORBObject, Sev, opdef, 

Sarglist) ; 



/* get default context */ 

rc = _get_default_context (SOMD_ORBObject, Sev, Sctx) ; 



/* 



put value and length into the NVList */ 

_get_item (arglist , Sev, 0, Sname, Stc, Sdummy, Sdummylen, 
S flags) ; 

_set_item (arglist , Sev, 0, name, tc, Sinput_value, 
sizeof (input_value) , flags) ; 




/* create the request - assume the object reference came from 
somewhere — from a file or returned by a previous request*/ 
rc = _create_request (ob j , &ev, ctx, 

"testMethod" , arglist, &result, &reqObj, 
(Flags) 0) ; 



/* invoke request */ 

rc = invoke (reqObj , &ev, (Flags) 0) ; 

/* print result */ 

printf ( "result : %s\n" , * (string*) (result . argument ._value) ) ; 
return ( 0 ) ; 



Creating user-supplied proxies 



DSOM uses a proxy object in the client's address space to represent the remote object. As mentioned earlier in this chapter, the proxy 
object encapsulates the operations necessary to forward and invoke methods on the remote object and return the results. By default, proxy 
generation is done automatically by the DSOM run time. However, if desired, the programmer can cause a user-supplied proxy class to be 
loaded instead of letting the run time dynamically generate a default proxy class. User-supplied proxies can be useful in specialized 
circumstances when local processing or data caching is desired. 

To build a user-supplied proxy class, it is necessary to understand a bit about how dynamic proxy classes are constructed by the DSOM run 
time. The DSOM run time constructs a proxy class by creating an instance of a class that inherits the interface and implementation of 
SOMDClientProxy, and the interface (but not the implementation) of the target class. The methods in the interface of the target object are 
all overridden to call the somDispatch method (For more details, see "Object references and proxy objects" in section 6.8.) 

Every SOM object contains the somDispatch method, inherited from SOMObject. This method is used to dynamically dispatch a method 
on an object, and can be overridden with application-specific dispatching mechanisms. In SOMDClientProxy, the somDispatch method is 
overridden to forward method calls to the corresponding remote target object. 

So, in effect, when a method is called on a default proxy object created by the DSOM run time, it redispatches the method to the remote 
object using DSOM's version of somDispatch. 

Below is a simple example of a user-supplied proxy class. In this particular example, the proxy object maintains a local, unshared copy of an 
attribute ("attributejong”) defined in the remote object ("Foo"), while forwarding method invocations ("methodl") on to the remote object. 
The result is that, when multiple clients are talking to the same remote "Foo" object, each client has a local copy of the attribute but all 
clients share the "Foo" object's implementation of "methodl". 

Note: It is important to understand that simply setting the attribute in one client's proxy does not affect the value of the attribute in other 
proxies. Maintaining consistency of the cached data values, if desired, is the responsibility of the user-supplied proxy class. 



Following is the IDL file for the "Foo" class: 

// foo.idl 



ftinclude <somdtype . idl> 
ftinclude <somobj.idl> 



interface Foo : SOMObject 
{ 

string methodl (out string a, inout long b, 
in Ref erenceData c) ; 
attribute long attribute_long; 



implementation 

{ 

releaseorder : methodl, „set_attribute_long, 
_get_attribute_long; 
dllname=" foo . dll " ; 
somDef aultlnit : override; 




The user-supplied proxy class is created by using multiple inheritance between SOMDClientProxy and the target object (in this case "Foo"). 
Thus, the IDL file for the user-supplied proxy class "Foo Proxy" (note the two underscores) is as follows: 



// fooproxy.idl 



#include <somdcprx . idl> 
#include <foo.idl> 



interface Foo Proxy : SOMDClientProxy, Foo 

{ 

implementation 

{ 

dllname=" f ooproxy . dll " ; 
methodl : override; 

} ; 



When a dynamic proxy class is created by the DSOM run time, the methods inherited from the target class are automatically overridden to 
use somDispatch. When you build a user-supplied proxy, you need to do this explicitly. This is why "methodl" is overridden in the 
implementation section of the "fooproxy.idl" file. 

The implementation of "methodl", which was added to the template produced by the SOM Compiler, simply calls the somDispatch method 

on "somSelf" Because "Foo Proxy" has inherited the implementation of SOMDClientProxy, calling somDispatch within "methodl" sends 

the method to the remote "Foo" object. 

/* fooproxy.c */ 

#include <somdtype.h> 

#include <f ooproxy . ih> 

SOM_Scope string SOMLINK methodl (Foo Proxy somSelf , 

Environment *ev, 
string* a, long* b, 

ReferenceData* c) 

{ 

string ret_str; 
somld methodld; 



/* Foo ProxyData *somThis = Foo ProxyGetData (somSelf ) ; */ 

Foo ProxyMethodDebug ( "Foo. .Proxy", "methodl") ; 



/* redispatch method, remotely */ 
methodld = somldFromString ( "methodl ") ; 
_somDispatch (somSelf, (void**) &ret_str, 

methodld, somSelf, ev, a, b, c) ; 
SOMFree (methodld) ; 



return ret_str; 

} 



In summary, to build a user-supplied proxy class: 

• Create the .idl file with the proxy class inheriting from both SOMDClientProxy and from the target class. Important: The 

user-supplied proxy class must be named "<targetClassName> Proxy" (with two underscores in the name) and 

SOMDClientProxy must be the first c/ass in the list of parent classes; for example, 



interface Foo_ _Proxy : SOMDClientProxy, Foo 



Putting SOMDClientProxy first ensures that its version of somDispatch will be used to dispatch remote method calls. 

In the implementation section of the .idl file, override all methods that are to be invoked on the target class. Do not override 




methods that are to be invoked on the local proxy. 

Compile the .idl file. Be sure the Interface Repository gets updated with the .idl file. In the implementation file, for each 
overridden method, call somDispatch with the method name and parameters passed into the overridden method. If the proxy 
class provides an implementation for the somlnit or somDefaultlnit method, then it is important to ensure that calling that 
method more than once on the same proxy object has no negative effect. 

Build the DLL and place it the LIBPATH for AIX and OS/2, or listed in PATH for Windows. Before creating the default proxy, the 

DSOM run time checks the LIBPATH for a DLL containing the class named "<targetClassName> Proxy" If such a DLL is 

found, DSOM loads it instead of dynamically generating a proxy class. 



Customizing the default base proxy class 



Continuing the example from the previous topic, imagine that an application derives 1 00 subclasses from the "Foo" class. If the application 
wishes to cache the "Foo::attribute_long" attribute in the proxies for all remote Foo-based objects, the application could supply 100 
user-supplied proxy classes, developed in the manner described above. However, this would become a very tedious and repetitive task! 

Alternatively, it is possible to provide a customized base proxy class for use in the dynamic generation of DSOM proxy classes. This allows 
an application to provide a customized base proxy class, from which other dynamic DSOM proxy classes can be derived. This is particularly 
useful in situations where an application would like to enhance many or all dynamically generated proxy classes with a common feature. 

As described in the previous topic, proxy classes are derived from the SOMDClientProxy class by default. It is the SOMDClientProxy class 
that overrides somDispatch in order to forward method calls to remote objects. 

The SOMDClientProxy class can be customized by deriving a subclass in the usual way (being careful not to replace somDispatch or 
other methods that are fundamental to implementing the proxy's behavior). To extend the above example further, the application might 
define a base proxy class called "MyClientProxy" that defines a long attribute called "attributejong," which will be inherited by Foo-based 
proxy classes. 

The SOM IDL modifier baseproxyclass can be used to specify which base proxy class DSOM should use during dynamic proxy-class 
generation. To continue the example, if the class "MyClientProxy" were used to construct the proxy class for a class "XYZ," then the 
baseproxyclass modifier would be specified s follows: 

// xyz.idl 

♦include <somdtype . idl> 

♦include <foo.idl> 

interface XYZ : Foo 
{ 

implementation 

{ 

baseproxyclass = MyClientProxy; 

} ; 

} ; 



It should be noted that: 

• Base proxy classes must be derived from SOMDClientProxy. 

• If a class "XYZ" specifies a custom base-proxy class, as in the above example, subclasses of "XYZ" do not inherit the value of 
the baseproxyclass modifier. If needed, the baseproxyclass modifier must be specified explicitly in each class. 



Sockets class 



To aid in portability, DSOM has been written to use a common communications interface, which is implemented by one or more available 
local protocols. 




The common communications interface is represented as an abstract class, called Sockets, and is based on the familiar "sockets" interface. 
Several protocol implementations are supported as Sockets subclasses: TCPIPSockets (and TCPIPSockets32 for OS/2) for TCP/IP, the 
class NBSockets for Netbios, and the class IPXSockets for Netware IPX/SPX. (The libraries included in a particular SOMobjects run-time 
package will vary.) 

There is one case where a Sockets subclass is not required: the DSOM Workstation run-time package uses shared memory to pass 
messages within a single machine, and bypasses the use of a Sockets subclass. (The SOMSOCKETS environment variable is ignored.) 

When the Event Management Framework (EMan) is used with DSOM, a Sockets subclass will be needed to support EMan, whether or not 
the application runs completely within a single machine. 

Appendix C, "Implementing Sockets Subclasses," describes how an application might provide its own Sockets subclass implementation, for 
special circumstances. 



Error Reporting and Troubleshooting 



When the DSOM run-time environment encounters an error during execution of a method or procedure, a SYSTEM_EXCEPTION will be 
raised. The standard system exceptions are discussed in the topic "Exceptions and Error Flandling" in Chapter 3 "Using SOM Classes in 
Client Programs." The "minor" field of the returned exception value will contain a DSOM error code. The DSOM error codes are listed below. 

Although a returned exception value can indicate that a DSOM run-time error occurred, it may be difficult for the user or application to 
determine what caused the error. Consequently, DSOM has been enabled to report run-time error information, for interpretation by IBM 
support personnel. These error messages take the following form: 



DSOM <type> error: <code> [<name>] at <f ile> : <line> 



where the arguments are as follows: 



type SYSTEM_EXCEPTION type, 

code DSOM error code, 

name symbol for DSOM error code (from "somderr . h" ) , 
file source-file name where the error occurred, and 

line line number where the error occurred. 



For example, 

DSOM NO_MEMORY error: 30001 [ SOMDERROR_NoMemory ] at somdob j . c : 250 



indicates that a "NO_MEMORY" error (error code 30001) occurred in file "somdobj.c" at line 250. This information is not usually meaningful 
to the user; it provides IBM support personnel with a starting point for problem analysis. There will often be a sequence of error messages; 
together they indicate the context in which the error occurred. It is important to give all reported messages to IBM support personnel for 
analysis. 

There is an environment variable, SOMDDEBUG, which is used to activate error reporting. There is a corresponding global variable that can 
be set by an application program; it is declared as: 

extern long SOMD_DebugFlag; 



Error reporting is normally disabled. To enable error reporting, the environment variable SOMDDEBUG should be set to a value greater than 
0. To disable error reporting, SOMDDEBUG should be set to a value less than or equal to 0. 

By default, error messages will display on the standard output device. Error messages can also be redirected to a log file. For this, the 
environment variable SOMDMESSAGELOG should be set to the pathname of the log file. The SOMD_ Init procedure opens the file named 
in SOMDMESSAGELG (if any), during process initialization. 



Error codes 




The error codes that may be encountered when using DSOM are listed in Appendix A, "SOMobjects Error Codes," which contains the codes 
for the entire SOMobjects Toolkit. 



Troubleshooting hints 



The following hints may prove helpful as you develop and test your DSOM application. 



Checking the DSOM setup 



This checklist will help you make certain that the DSOM environment is set up correctly. 

1 . Use the somdchk tool to verify the settings of various DSOM environment variables. Note that if the SOMIR environment 
variable contains relative pathnames, the client programs, server programs, and somdd daemon must be started from the same 
directory. (Instead, it is recommended that SOMIR contain full pathnames.) 

2. For all application classes, IDL must be compiled into the Interface Repository. You can verify that a class exists in the Interface 
Repository by executing "irdump<class>" on AIX or OS/2, or, on Windows, click on the IRDUMP icon and browse for the 
appropriate class. See "Registering class interfaces" for more information. 

3. An implementation (a server program and class libraries) must be registered with DSOM by running the regimpl utility. See 
"Registering servers and classes" for more information. 

4. Verify that all class libraries and networking libraries are in directories specified in LIBPATFI. 



Analyzing problem conditions 



The DSOM error codes mentioned below can be obtained directly by the application from the "minor" field of the exception data returned in a 
system exception, or from an error report message when SOMDDEBUG is set to a positive integer value (see the previous topic, "Error 
reporting”). 

Symptom: When running regimpl, a "PERSIST_STORE” or "NOJMPLEMENT" exception is returned. The DSOM error code is 
SOMDERRORJO or SOMDERROR_NolmplDatabase. 

• This may indicate that the Implementation Repository files are not found or cannot be accessed. Verify that SOMDDIR is set 
correctly, to a directory that has granted read/write permission to the DSOM user. (It is best if the directory name is fully 
qualified.) If the SOMDDIR variable is not set, verify that the default directory ($SOMBASE/etc/dsom on AIX, and 
%SOMBASE%\etc\dsom on OS/2 or Windows) has been set up with the correct permissions. Ensure that the the files contained 
in the directory all have read/write permission granted to the DSOM user. 

Symptom: When starting somdd, an "INITIALIZE" exception is returned with error code SOMDAIreadyRunning. 

• This indicates that there is already an instance of somdd running. If the current instance of somdd does not seem to be 
responding properly, delete all instances of somdd and restart a new copy of somdd. 

Symptom: When starting up a server program, an exception is returned with a DSOM error code of SOMDERROR_ServerAlreadyExists. 

• This may indicate that a server process that is already running has already registered itself with the DSOM daemon, somdd, 
using the implementation ID of the desired server program. 

Symptom: On OS/2, an operating system error occurs indicating a "stack overflow" condition soon after a the first call to a class DLL. 
Rebuilding the DLL with a larger stack size does not help. 

• This sometimes occurs when a DLL uses, but does not initialize, the run time for OS/2. To perform the proper initialization, a 
function named "_DLL_lnitTerm" must be included in the DLL, and it must invoke the C Set/2 initialization function, "_CRT_lnit." 




The _DLL_lnitTerm function is invoked automatically when the DLL is loaded. 

An example _DLL_lnitTerm function is included in the DSOM sample code shipped with the SOMobjects Developer Toolkit for 
OS/2, in the file "initterm.c". 

Symptom: When running a DSOM application that uses EMan, an error message is displayed asking that the SOMSOCKETS be set. 

• This may indicate a need to specify the Sockets subclass to be used with the application. Current choices are TCPIPSockets 
for TCP/IP (and TCPIPSockets32 on OS/2), NBSockets for NetBios and IPXSockets for Netware IPX/SPX. Note:Each 
SOMobjects package will contain an appropriate subset of Sockets subclasses. Workstation DSOM includes TCPIPSockets (and 
TCPIPSockets32 onOS/2 ) for TCP/IP. Workgroup DSOM also includes NBSockets for NetBios and IPXSockets for Netware. 

Symptom: A remote method invocation fails and an "INTF_REPOS" exception is returned. The DSOM error code is 
SOMDERROR_BadDescriptor or SOMDERROR_ClassNotlnlR. 

• This may indicate that the interface describing the method or the method itself cannot be found in the Interface Repository. Verify 
that SOMIR is set correctly, and that the IR contains all interfaces used by your application. 

If the default SOM IR (supplied with the SOMobjects Toolkit and Runtimes) is not used by the application, the user's IR must 
include the interface definitions for the appropriate Sockets class, server class (derived from SOMDServer), and the definitions 
of the standard DSOM exceptions (found in file "stexcep.idl”) that may be returned by a method call. 

Symptom: A SOMDERROR_ClassNotFound error is returned by a client either when creating a remote object using somdNewObject, or 
when finding a server object using somdFindAnyServerByClass. (The methods are defined on the SOMDObjectMgr class.) 

• This occurs when the class name specified in calls to somdNewObject or somdFindAnyServerByClass cannot be found in the 
Implementation Repository. Make sure that the class name has been associated with at least one of the server implementations. 

Symptom: A SOMDERROR_ClassNotlnlR error is returned by a server when creating a new object using somdNewObject, 
somdCreateObj, or somdGetClassObj. 

• This error may result if the DLL for the class cannot be found. Verify hat: 

-the interface of the object can be found in the IR; 

-the class name is spelled correctly and is appropriately scoped (for example, the "Printer" class in the "PrintServer" 
module must have the identifier "PrintServer:: Printer"). 

• This error can also result when the shared library is statically linked to the server program, but the <c/ass/Vai 77£>>NewClass 
procedures have not been called to initialize the classes. 

Symptom: When invoking a method returns a proxy for a remote object in the client, a SOMDERROR_NoParentClass error occurs. 

• This error may result when the class libraries used to build the proxy class are statically linked to the program, but the 
<c/assA/ame>He\NC\ass procedure have not been called to initialize the classes. 

Symptom: Following a method call, the SOM run-time error message, "A target object failed basic validity checks during method resolution" 
is displayed. 

• Usually this means that the method call was invoked using a bad object pointer, or the object has been corrupted. 

Symptom: A remote object has an attribute or instance variable that is, or contains, a pointer to a value in memory (for example, a string, a 
sequence, an "any"). The attribute or instance variable value is set by the client with one method call. When the attribute or instance variable 
is queried in a subsequent method call, the value referenced by the pointer is "garbage". 

• This may occur because DSOM makes a copy of argument values in a client call, for use in the remote call. The argument 
values are valid for the duration of that call. When the remote call is completed, the copies of the argument values are freed. 

In a DSOM application, a class should not assume ownership of memory passed to it in a method parameter unless the IDL 
description of the method includes the SOM IDL modifier object_owns_parameters. Otherwise, if a parameter value is meant to 
persist between method invocations, then the object is responsible for making a copy of the parameter value. 

Symptom: A method defines a (char *) parameter that is used to pass a string input value to an object. The object attempts to print the 
string value, but it appears to be "garbage". 

• DSOM will support method arguments that are of type "pointer-to-X" (pointer types are a SOM extension), by dereference the 
pointer in the call, and copying the base value. The pointer-to-value is reconstructed on the server before the actual method call 
is made. 

While (char *) is commonly used to refer to NULL-terminated strings in C programs, (char *) could also be a pointer to a single 
character or to an array of characters. Thus, DSOM interprets the argument type literally as a pointer-to-one-character. 

To correctly pass strings or array arguments, the appropriate CORBA type should be used (for example, "string" or "char foo[4 




]")■ 



Symptom: A segmentation violation occurs when passing an "any" argument to a method call, where the "any" value is a string, array, or 

object reference. Note: The NamedValues used in Dll calls use "any" fields for the argument values. 

• This error may occur because the ”_value" field of the "any" structure does not contain the address of a pointer to the target 
string, array, or object reference, as it should. (A common mistake is to set the "_value" field to the address of the string, array, 
or object reference itself.) 

Symptom: When a server program or a server object makes a call to get_id or to get_SOM_object on a SOMDObject, a 

"BAD_OPERATION" exception is returned with an error code of SOMDERROR_WrongRefType. 

• This error may occur when the operation getjd is called on a SOMDObject that does not have any user-supplied 
ReferenceData (that is, the SOMDObject is a proxy, is nil, or is a simple "SOM ref" created by create_SOM_ref). Likewise, this 
error may occur when the operation get_SOM_object is called on a SOMDObject that was not created by the create_SOM_ref 
method. 

Symptom: A segmentation fault occurs when a SOMD_Uninit call is executed. 

• This error could occur if the application has already freed any of the DSOM run-time objects that were allocated by the 
SOMD Init call, including SOMD ObjectMgr, SOMDImpIRepObject and SOMD ORBObject. 

Symptom: Unexplained program crashes. 

• Verify that all DSOM environment variables are set, as described in the earlier section "Configuring DSOM Applications". Verify 
that all class libraries are in directories specified in LIBPATH for AiX and OS/2, or specified in PATH for Windows. Verify that the 
contents of the Interface Repository, specified by SOMIR, are correct. Verify that the contents of the Implementation Repository, 
specified by SOMDDIR, are correct. Verify that somdd is running. Set SOMDDEBUG to 1 to obtain additional DSOM error 
messages. 

Symptom: When starting somdd, an "INITIALIZE" error is returned with error code SOMDERROR_NoSocketsClass. 

• If SOMSOCKETS is set, verify that the IR contains the appropriate Sockets interface definition. 



Limitations 



The following list indicates known limitations of Distributed SOM at the time of this release. 

1 . Currently, objects cannot be moved from one server to another without changing the object references (i.e., deleting the object, 
and creating it anew in another server). This yields ali copies of the previous reference invalid. 

2. The changejmplementation method is not supported. This method, defined by the BOA interface, is intended to allow an 
application to change the implementation definition associated with an object. However, in DSOM, changing the server 
implementation definition may render existing object references (which contain the old server ID) invalid. 

3. Currently, DSOM has a single server activation policy, which corresponds to CORBA's "shared" activation policy for dynamic 
activation, and "persistent" activation policy for manual activation. Other activation policies, such as "server-per-method" and 
"unshared" are not directly supported, and must be implemented by the application. 

Since the unshared server policy is not directly supported, the object_is_ready and deactivate_obj methods, defined in the 
BOA interface have null implementations. 

4. If a server program terminates without calling deactivate_impl, subsequent attempts to start that server may fail. The DSOM 
daemon believes the server is still running until it is told it has stopped. Attempts to start a server that is believed to be exist 
results in an error (SOMDERROR_ServerAlreadyExists). 

5. Currently, file names used in ImplementationDefs are limited to 255 bytes. Implementations aliases used in 
ImplementationDefs are limited to 50 bytes. Class names used in the Implementation Repository are limited to 50 bytes. 
Hostnames are limited to 32 bytes. 

6. The OUT_LIST_MEMORY, IN_COPY_VALUE, and DEPENDENTJJST flags, used with Dynamic Invocation Interface, are not 
yet supported. 

7. The Context::get_values method currently does not support the flag CTX_RESTRICT_SCOPE. 



Other important notes concerning DSOM are documented in the "README" file in the SOMBASE root directory ($SOMBASE on AIX, and 




%SOMBASE% on OS/2 or Windows). 



The SOM Interface Repository Framework 



This section covers the following subjects: 

• Introduction 

• Using the SOM Compiler to Build an Interface Repository 

• Managing Interface Repository files 

• Programming with the Interface Repository Objects 



Introduction 



The SOM Interface Repository (IR) is a database that the SOM Compiler optionally creates and maintains from the information supplied in 
IDL source files. The Interface Repository contains persistent objects that correspond to the major elements in IDL descriptions. The SOM 
Interface Repository Framework is a set of classes that provide methods whereby executing programs can access these objects to discover 
everything known about the programming interfaces of SOM classes. 

The programming interfaces used to interact with Interface Repository objects, as well as the format and contents of the information they 
return, are architected and defined as part of the Object Management Group's CORBA standard. The classes composing the SOM Interface 
Repository Framework implement the programming interface to the CORBA Interface Repository. Accordingly, the SOM Interface 
Repository Framework supports all of the interfaces described in The Common Object Request Broker; Architecture and Specification 
(OMG Document Number 91 .12.1 , Revision 1.1 , chapter 7). 

As an extension to the CORBA standard, the SOM Interface Repository Framework permits storage in the Interface Repository of arbitrary 
information in the form of SOM IDL modifiers. That is, within the SOM-unique implementation section of an IDL source file or through the 
use of the #pragma modifier statement, user-defined modifiers can be associated with any element of an IDL specification. (See the 
section entitled "SOM Interface Definition Language" in Chapter 4, "SOM IDL and the SOM Compiler.") When the SOM Compile creates the 
Interface Repository from an IDL specification, these potentially arbitrary modifiers are stored in the IR and can then be accessed via the 
methods provided by the Interface Repository Framework. 

This chapter describes, first, how to build and manage interface repositories, and second, the programming interfaces embodied in the SOM 
Interface Repository Framework. 



Using the SOM Compiler to Build an Interface Repository 



The SOMobjects Toolkit includes an Interface Repository emitter that is invoked whenever the SOM Compiler is run using an sc command 
with the -u option (which "updates" the interface repository). The IR emitter can be used to create or update an Interface Repository file. The 
IR emitter expects that an environment variable, SOMIR, was first set to designate a file name for the Interface Repository. For example, to 
compile an IDL source file named "newels. idl" and create an Interface Repository named "newels. ir", use a command sequence similar to 
the following: 

For OS/2: 

set SOMIR=c : \myf iles\newcls . ir 
sc -u newels 



For AIX: 

export SOMIR=~/newcls . ir 
sc -u newels 



If the SOMIR environment variable is not set, the Interface Repository emitter creates a file named "som.ir” in the current directory. 




The sc or some command runs the Interface Reposito emitter plus any other emitters indicated by the environment variable SMEMIT 
(described in the topic "Running the SOM Compiler" in Chapter 4, "Implementing SOM Classes"). To run the Interface Repository emitter by 
itself, issue the sc command with the -s option (which overrides SMEMIT) set to "ir". For example: 



sc -u -sir newels 
some -u -sir newels 

or equivalently, 

sc -usir newels 
some -usir newels 



(ON OS/2 or AIX) 
(On Windows) 



(On OS/2 or AIX) 
(On Windows) 



The Interface Repository emitter uses the SOMIR environment variable to locate the designated IR file. If the file does not exist, the IR 
emitter creates it. If the named interface repository already exists, the IR emitter checks all of the "type" information in the IDL source file 
being compiled for internal consistency, and then changes the contents of the interface repository file to agree with with the new IDL 
definition. For this reason, the use of the -u compiler flag requires that all of the types mentioned in the IDL source file must be fully defined 
within the scope of the compilation. Warning messages from the SOM Compiler about undefined types result in actual error messages when 
using the -u flag. 

The additional type checking and file updating activity implied by the -u flag increases the time it takes to run the SOM Compiler. Thus, when 
developing an IDL class description from scratch, where iterative changes are to be expected, it may be preferable not to use the -u 
compiler option until the class definition has stabilized. 



Managing Interface Repository files 



Just as the number of interface definitions contained in a single IDL source file is optional, similarly, the number of IDL files compiled into 
one interface repository file is also at the programmer's discretion. Commonly, however, all interfaces needed for a single project or class 
framework are kept in one interface repository. 



The SOM IR file "som.ir" 



The SOMobjects Toolkit includes an Interface Repository file ("som.ir") that contains objects describing all of the types, classes, and 
methods provided by the various frameworks of the SOMobjects Toolkit. Since all new classes will ultimately be derived from these 
predefined SOM classes, some of this information also needs to be included in a programmer's own interface repository files. 

For example, suppose a new class, called "MyClass", is derived from SOMObject. When the SOM Compiler builds an Interface Repository 
for "MyClass", that IR will also include all of the information associated with the SOMObject class. This happens because the SOMObject 
class definition is inherited by each new class; thus, all of the SOMObject methods and typedefs are implicitly contained in the new class as 
well. 

Eventually, the process of deriving new classes from existing ones would lead to a great deal of duplication of information in separate 
interface repository files. This would be inefficient, wasteful of space, and extremely difficult to manage. For example, to make an 
evolutionary change to some class interface, a programmer would need to know about and subsequently update all of the interface 
repository files where information about that interface occurred. 

One way to avoid this dilemma would be to keep all interface definitions in a single interface repository (such as "som.ir"). This is not 
recommended, however. A single interface repository would soon grow to be unwieldy in size and become a source of frequent access 
contention. Everyone involved in developing class definitions would need update access to this one file, and simultaneous uses might result 
in longer compile times. 



Managing IRs via the SOMIR environment variable 



The SOMobjects Toolkit offers a more flexible approach to managing interface repositories. The SOMIR environment variable can reference 
an ordered list of separate IR files, which process from left to right. Taken as a whole, however, this gives the appearance of a single, logical 
interface repository. A programmer accessing the contents of "the interface repository” through the SOM Interface Repository framework 
would not be aware of the division of information across separate files. It would seem as though all of the objects resided in a single 




interface repository file. 



A typical way to utilize this capability is as follows: 

• The first (leftmost) Interface Repository in the SOMIR list would be "som.ir". This file contains the basic interfaces and types 
needed in all SOM classes. 

• The second file in the list might contain interface definitions that are used globally across a particular enterprise. 

• A third interface repository file would contain definitions that are unique to a particular department, and so on. 

• The final interface repository in the list should be set aside to hold the interfaces needed for the project currently under 
development. 

Developers working on different projects would each set their SOMIR environment variables to hold slightly different lists. For the most part, 
the leftmost portions of these lists would be the same, but the rightmost interface repositories would differ. When any given developer is 
ready to share his/her interface definitions with other people outside of the immediate work group, that person's interface repository can be 
promoted to inclusion in the master list. 

With this arrangement of IR files, the more stable repositories are found at the left end of the list. For example, a developer should never 
need to make any significant changes to "som.ir”, because these interfaces are defined by IBM and would only change with a new release of 
the SOMobjects Toolkit. 

The Interface Repository Framework only permits updates in the rightmost file of the SOMIR interface repository list. That is, when the SOM 
Compiler -u flag is used to update the Interface Repository, only the final file on the IR list will be affected. The information in all preceding 
interface repository files is treated as "read only". Therefore, to change the definition of an interface in one of the more global interface 
repository files, a developer must overtly construct a special SOMIR list that omits all subsequent (that is, further to the right) interface 
repository files, or else petition the owner of that interface to make the change. 

It is important the the rightmost filename in the SOMIR interface repository list not appear elsewhere in the list. For Example, the following 
setting for SOMIR: 

%SOMBASE5\ETC\SOM. IR; SOM.IR; C : \IR\COMPANY . IR; SOM.IR 



would cause problems when attempting to update the SOM.IR file, because SOM.IR appears twice in the list. 

Flere is an example that illustrates the use of multiple IR files with the SOMIR environment variable. In this example, the SOMBASE 
environment variable represents the directory in which the SOMobjects Toolkit files have been installed. Only the "myown.ir" interface 
repository file will be updated with the interfaces found in files "myclassl .idl", "myclass2.idl", and "myclass3.idl". 

For OS/2: 

set BASE_IRLIST=%SOMBASE%\ IR\SOM . IR; C : \IR\COMPANY . IR; C : \ IR\DEPT1 0 . IR 
set SOMIR=%BASE_IRLIST% ; D : \MYOWN . IR 

set SMINCLUDE= . ; %SOMBASE% \ INCLUDE ; C : \COMPANY\ INCLUDE ; C : \DEPT1 0 \ INCLUDE 
sc -usir myclassl 
sc -usir myclass2 
sc -usir myclass3 



For AIX: 

export BASE_IRLIST=$SOMBASE/ ir/ som. ir : / usr/ local/ ir/comany . ir : \ 
/usr/ local /ir/ dept 10 . ir 
export SOMIR=$BASE_IRLIST : ~/myown . ir 

export SMINCLUDE= . : $SOMBASE/ INCLUDE : /usr/local/company/include : \ 
/usr/ local /dept 10 /include 
sc -usir myclassl 
sc -usir myclass2 
sc -usir myclass3 



Placing 'private' information in the Interface Repository 



When the SOM Compiler updates the Interface Repository in response to the -u flag, it uses all of the information available from the IDL 
source file. Flowever, if the PRIVATE preprocessor variable is used to designate certain portions of the IDL file as private, the 




preprocessor actually removes that information before the SOM Compiler sees it. Consequently, private information will not appear in the 
Interface Repository unless the -p compiler option is also used in conjunction with -u. For example: 

sc -up myclassl (On AIX or OS/2) 

some -up myclassl (On Windows) 



This command will place all of the information in the "myclassl .idl" file, including the private portions, in the Interface Repository. 

If you are using tools that understand SOM and rely on the Interface Repository to describe the types and instance data in your classes, you 
may need to include the private sections from your IDL source files when building the Interface Repository. 



Programming with the Interface Repository Objects 



The SOM Interface Repository Framework provides an object-oriented programming interface to the IDL information processed by the SOM 
Compiler. Unlike many frameworks that require you to inherit their behavior in order to use it, the Interface Repository Framework is useful in 
its own right as a set of predefined objects that you can access to obtain information. Of course, if you need to subclass a class to modify its 
behavior, you can certainly do so; but typically this is not necessary. 

The SOM Interface Repository contains the fully-analyzed (compiled) contents of all information in an IDL source file. This information takes 
the the form of persistent objects that can be accessed from a running program. There are ten classes of objects in the Interface Repository 
that correspond directly to the major elements in IDL source files; in addition, one instance of another class exists outside of the IR itself, as 
follows: 



Contained 

Container 

ModuleDef 

InterfaceDef 

AttributeDef 

OperationDef 

ParameterDef 

TypeDef 

ConstantDef 

ExceptionDef 

Repository 



All objects in the Interface Repository are instances of classes derived from this 
class and exhibit the common behavior defined in this interface. 

Some objects in the Interface Repository hold (or contain) other objects. (For 
example, a module [ModuleDef] can contain an interface [InterfaceDef].) All 
Interface Repository objects that hold other objects are instances of classes 
derived from this class and exhibit the common behavior defined by this class. 

An instance of this class exists for each module defined in an IDL source file. 

ModuleDefs are Containers, and they can hold ConstantDefs, TypeDefs, 
ExceptionDefs, InterfaceDefs, and other ModuleDefs. 

An instance of this class exists for each interface named in an IDL source file. 
(One InterfaceDef corresponds to one SOM class.) InterfaceDefs are 
Containers, and they can hold ConstantDefs, TypeDefs, ExceptionDefs, 
AttributeDefs, and OperationDefs. 

An instance of this class exists for each attribute defined in an IDL source file. 
AttributeDefs are found only inside of (contained by) InterfaceDefs. 

An instance of this class exists for each operation (method, _set_method, and 
_get_method) defined in an IDL source file. OperationDefs are Containers that 
can hold ParameterDefs. OperationDefs are found only inside of (contained by) 

InterfaceDefs. 

An instance of this class exists for each parameter of each operation (method) 
defined in an IDL source file. ParameterDefs are found only inside of (contained 

by) OperationDefs. 

An instance of this class exists for each typedef, struct, union, or enum defined 
in an IDL source file. TypeDefs may be found inside of (contained by) any 
Interface Repository Container except an OperationDef. 

An instance of this class exists for each constant defined in an IDL source file. 
ConstantDefs may be found inside (contained by) of any Interface Repository 
Container except an OperationDef. 

An instance of this class exists for each exception defined in an IDL source file. 
ExceptionDefs may be found inside of (contained by) any Interface Repository 
Container except an OperationDef. 

One instance of this class exists for the entire SOM Interface Repository, to hold 
IDL elements that are global in scope. The instance of this class does not, 




however, reside within the IR itself. 



Methods introduced by Interface Repository classes 



The Interface Repository classes introduce nine new methods, which are briefly described below. Many of the classes simply override 
methods to customize them for the corresponding IDL element; this is particularly true for classes representing IDL elements that are only 
contained within another syntactic element. Full descriptions of each method are found in the SOMobjects Deve/oper Too/k/t: Programmers 
Reference Manua/. 

• Contained class methods (a// IR objects are instances of this class and exhibit this behavior): 

describe Returns a structure of type Description containing all 

information defined in the IDL specification of the syntactic 
element corresponding to the target Contained object. For 
example, for a target InterfaceDef object, the describe 
method returns information about the IDL interface 
declaration. The Description structure contains a "name" 
field with an identifier that categorizes the description (such 
as, "InterfaceDescription") and a "value" field holding an 
"any" structure that points to another structure containing 
the IDL information for that particular element (in this 
example, the interface's IDL specifications). 

within Returns a sequence designating the object(s) of the IR 

within which the target Contained object is contained. For 
example, for a target TypeDef object, it might be contained 
within any other IR object(s) except an OperationDef 
object. 

• Container class methods ( some IR objects contain other objects and exhibit this behavior): 

contents Returns a sequence of pointers to the object(s) of the IR 

that the target Container object contains. (For example, for 
a target InterfaceDef object, the contents method returns 
a pointer to each IR object that corresponds to a part of the 
IDL interface declaration.) The method provides options for 
excluding inherited objects or for limiting the search to only 
a specified kind of object (such as AttributeDefs). 

describe_contents Combines the describe and contents methods; returns a 

sequence of ContainerDescription structures, one for 
each object contained by the target Container object. Each 
structure has a pointer to the related object, as well as 
"name" and "value" fields resulting from the describe 
method. 

lookup_name Returns a sequence of pointers to objects of a given name 

contained within a specified Container object, or within 
(sub)objects contained in the specified Container object. 

• ModuleDef class methods : 

Override describe and within. 

• InterfaceDef class methods : 

describe_interface Returns a description of all methods and attributes of a 

given interface definition object that are held in the 
Interface Repository. 

Also overrides describe and within. 

• AttributeDef class method : 



Overrides describe. 




QperationDef class method : 



Overrides describe. 



ParameterDef class method : 



TvpePef class method : 



ConstantPef class method : 



ExceptionPef class method : 



Overrides describe. 



Overrides describe. 



Overrides describe. 



Overrides describe. 



Repository class methods : 

lookupjd 



lookupmodifier 



release_cache 



Returns the Contained object that has a specified 

Repositoryld. 

Returns the string value held by a SOM or user-defined 
modifier, given the name and type of the modifier, and the 
name of the object that contains the modifier. 

Releases, from the internal object cache, the storage used 
by all currently unreferenced Interface Repository objects. 



Accessing objects in the Interface Repository 



As mentioned above, one instance of the Repository class exists for the entire SOM Interface Repository. This object does not, itself, reside 
in the Interface Repository (hence it does not exhibit any of the behavior defined by the Contained class). It is, however, a Container, and it 
holds all ConstantPefs, TypePefs, ExceptionPefs, InterfacePefs, and ModulePefs that are global in scope (that is, not contained inside 
of any other Containers). 

When any method provided by the Repository class is used to locate other objects in the Interface Repository, those objects are 
automatically instantiated and activated. Consequently, when the program is finished using an object from the Interface Repository, the 
client code should release the object using the somFree method. 

All objects contained in the Interface Repository have both a "name" and a "Repository ID" associated with them. The name is not 
guaranteed to be unique, but it does uniquely identify an object within the context of the object that contains it. The Repository ID of each 
object is guaranteed to uniquely identify that object, regardless of its context. 

For example, two TypeDef objects may have the same name, provided they occur in separate name scopes (ModulePefs or 
InterfacePefs). In this case, asking the Interface Repository to locate the TypePef object based on its name would result in both TypePef 
objects being returned. On the other hand, if the name is looked up from a particular ModulePef or InterfacePef object, only the TypePef 
object within the scope of that ModulePef or InterfacePef would be returned. By contrast, once the Repository ID of an object is known, 
that object can always be directly obtained from the Repository object via its Repository ID. 

C or C++ programmers can obtain an instance of the Repository class using the RepositoryNew macro. Programmers using other 
languages (and C/C++ programmers without static linkage to the Repository class) should invoke the method somGetlnterfaceRepository 

on the SOMCIassMgrObject . For example, 

For C or C++ (static linkage): 

/(include <repostry.h> 

Repository repo; 

repo = RepositoryNew () ; 



From other languages (and for dynamic linkage in C/C++): 




1 . Use the somEnvironmentNew function to obtain a pointer to the SOMCIassMgrObject, as described in Chapter 3, "Using SOM 
Classes." 

2. Use the somResolve or somResolveByName function to obtain a pointer to the somGetlnterfaceRepository method 
procedure. 

3. Invoke the method procedure on the SOMCIassMgrObject, with no additional arguments, to obtain a pointer to the Repository 
object. 

After obtaining a pointer to the Repository object, use the methods it inherits from Container or its own lookupjd method to instantiate 
objects in the Interface Repository. As an example, the contents method shown in the C fragment below activates every object with global 
scope in the Interface Repository and returns a sequence containing a pointer to every global object: 

ftinclude <containd.h> /* Behavior common to all 

IR objects */ 

Environment *ev; 
int i; 

sequence (Contained) everyGlobalOb ject ; 

ev = SOM_CreateLocalEnvironment ( ) ; /* Get an environment to use */ 
printf ("Every global object in the Interface Repository : \n" ) ; 

everyGlobalOb ject = Container_contents (repo, ev, "all", TRUE); 

for (i=0; i < everyGlobalOb ject ._length; i++) { 

Contained aContained; 

aContained = (Contained) everyGlobalOb ject ._buffer [ i ] ; 
printf ("Name: %s. Id: %s\n", 

Contained get_name (aContained, ev) , 

Contained get_id (aContained, ev) ) ; 

SOMOb ject_somFree (aContained) ; 

} 



Taking this example one step further, here is a complete program that accesses every object in the entire Interface Repository. It, too, uses 
the contents method, but this time recursively calls the contents method until every object in every container has been found: 

#include <stdio.h> 

#include <containd.h> 

#include <repostry.h> 

void showContainer (Container c, int *next) ; 

main () 

{ 

int count = 0; 

Repository repo; 

repo = RepositoryNew (); 

printf ("Every object in the Interface Repository : \n\n" ) ; 
showContainer ( (Container) repo, &count) ; 

SOMOb ject_somFree (repo) ; 

printf ("%d objects found\n", count); 

exit (0) ; 

} 



void showContainer (Container c, int *next) 

{ 

Environment *ev; 
int i; 

sequence (Contained) everyObject; 

ev = SOM_CreateLocalEnvironment (); /* Get an environment */ 
everyObject = Container_contents (c, ev, "all", TRUE); 

for (i=0; i<everyOb ject ._length; i++) { 

Contained aContained; 

(*next) ++; 

aContained = (Contained) everyOb ject ,_buf fer [ i ] ; 
printf ("%6d. Type: %-12s id: %s\n", *next, 

SOMOb ject_somGetClassName (aContained) , 

Contained get_id (aContained, ev) ) ; 

if (SOMOb ject_somIsA (aContained, _Container) ) 

showContainer ( (Container) aContained, next) ; 

SOMOb ject_somFree (aContained) ; 




Once an object has been retrieved, the methods and attributes appropriate for that particular object can then be used to access the 
information contained in the object. The methods supported by each class of object in the Interface Repository, as well as the classes 
themselves, are documented in the SOMobjects Deve/oper Too/kit: Programmers Reference Manuaf. 



A word about memory management 



Several conventions are built into the SOM Interface Repository with regard to memory management. You will need to understand these 
conventions to know when it is safe and appropriate to free memory references and also when it is your responsibility to do so. 

All methods that access attributes (such as, the _get_<attribute> methods) always return either simple values or direct 
references to data within the target object. This is necessary because these methods are heavily used and must be fast and efficient. 
Consequently, you should never free any of the memory references obtained through attributes. This memory will be released automatically 
when the object that contains it is freed. 

For all methods that give out object references (there are five: within, contents, lookup_name, lookupjd, and describe_contents), when 
finished with the object, you are expected to release the object reference bv invoking the somFree method. (This is illustrated in the sample 
program that accesses all Interface Repository objects.) Do not release the object reference until you have either copied or finished using all 
of the information obtained from the object. 

The describe methods (describe, describe_contents, and describe_interface) return structures and sequences that contain information. 
The actual structures returned by these methods are passed by value (and hence should only be freed if you have allocated the memory 
used to receive them). Flowever, you may be required to free some of the information contained in the returned structures when you are 
finished. Consult the specific method in the SOMobjects Deve/oper Too/kit: Programmers Reference Manua/ for more details about what to 
free. 

During execution of the describe and lookup methods, sometimes intermediate objects are activated automatically. These objects are kept 
in an internal cache of objects that are in use, but for which no explicit object references have been returned as results. Consequently, there 
is no way to identify or free these objects individually. Flowever, whenever your program is finished using all of the information obtained thus 
far from the Interface Repository, invoking the release cache method causes the Interface Repository to purge its internal cache of these 
implicitly referenced objects. This cache will replenish itself automatically if the need to do so subsequently arises. 



Using TypeCode pseudo-objects 



Much of the detailed information contained in Interface Repository objects is represented in the form of TypeCodes. TypeCodes are 
complex data structures whose actual representation is hidden. A TypeCode is an architected wav of describing in complete detail 
everything that is known about a particular data type in the IDL language, regardless of whether it is a (built-in) basic type or a 
(user-defined) aggregate type. 

Conceptually, every TypeCode contains a "kind" field (which classifies it), and one or more parameters that carry descriptive information 
appropriate for that particular category of TypeCode. For example, if the data type is long, its TypeCode would contain a "kind" field with 
the value tkjong. No additional parameters are needed to completely describe this particular data type, since long is a basic type in the 
IDL language. 

By contrast, if the TypeCode describes an IDL struct, its "kind" field would contain the value tk_struct, and it would possess the following 
parameters: a string giving the name of the struct, and two additional parameters for each member of the struct: a string giving the member 
name and another (inner) TypeCode representing the member's type. This example illustrates the fact that TypeCodes can be nested and 
arbitrarily complex, as appropriate to express the type of data they describe. Thus, a structure that has N members will have a TypeCode of 
tk_struct with 2N+1 parameters (a name and TypeCode parameter for each member, plus a name for the struct itself). 

A tk_union TypeCode representing a union with N members has 3N+2 parameters: the type name of the union, the switch TypeCode, 
and a label value, member name and associated TypeCode for each member. (The label values all have the same type as the switch, 
except that the default member, if present, has a label value of zero octet.) 

A tk_enum TypeCode (which represents an enum) has N+1 parameters: the name of the enum followed by a string for each enumeration 
identifier. A tk_string TypeCode has a single parameter: the maximum string length, as an integer. (A maximum length of zero signifies an 
unbounded string.) 

A tk_sequence TypeCode has two parameters: a TypeCode for the sequence elements, and the maximum size, as an integer. (Again, 




zero signifies unbounded.) 



A tk_array TypeCode has two parameters: a TypeCode for the array elements, and the array length, as an integer. (Arrays must be 
bounded.) 

The tk_objref TypeCode represents an object reference; its parameter is a repository ID that identifies its interface. 

A complete table showing the parameters of all possible TypeCodes is given in the SOMobjects Base Toolkit Programmers Reference 
Manual; see the TypeCode_kind function of the Interface Repository Framework. 

TypeCodes are not actually "objects” in the formal sense. TypeCodes are referred to in the CORBA standard as pseudo-objects and 
described as "opaque". This means that, in reality, TypeCodes are special data structures whose precise definition is not fully exposed. 
Their implementation can vary from one platform to another, but all implementations must exhibit a minimal set of architected behavior. SOM 
TypeCodes support the architected behavior and have additional capability as well (for example, they can be copied and freed). 

Although TypeCodes are not objects, the programming interfaces that support them adhere to the same conventions used for IDL method 
invocations in SOM. That is, the first argument is always a TypeCode pseudo-object, and the second argument is a pointer to an 
Environment structure. Similarly, the names of the TypeCode functions are constructed like SOM's C-language method-invocation macros 
(all functions that operate on TypeCodes are named function-name >). Because of this ostensible similarity to an IDL class, 

the TypeCode programming interfaces can be conveniently defined in IDL as shown below. 

A complete table showing the parameters of all possible TypeCodes is given in the SOMobjects Deve/oper Too/kit Programmers Reference 
Manuat; see the TypeCode_kind function of the Interface Repository Framework. 

interface TypeCode { 

enum TCKind { 

tk_null, tk_void, 

tk_short, tk_long, tk_ushort, tk_ulong, 

tk_float, tk_double, tk_boolean, tk_char, 

tk_octet, tk_any, tk_TypeCode, tk_Principal, tk_objref, 

tk_struct, tk_union, tk_enum, tk_string, 

tk_sequence, tk_array, 

// The remaining enumerators are SOM-unique extensions 
// to the CORBA standard. 

// 

tk_pointer, tk_self, tk_foreign 

} ; 



exception Bounds {}; 

// This exception is returned if an attempt is made 
// by the parameter () operation (described below) to 
// access more parameters than exist in the receiving 
// TypeCode. 

boolean equal (in TypeCode tc) ; 

// Compares the argument with the receiver and returns TRUE 
// if both TypeCodes are equivalent. This is NOT a test for 
// identity. 

TCKind kind (); 

// Returns the type of the receiver as a TCKind. 
long param_count (); 

// Returns the number of parameters that make up the 
// receiving TypeCode. 

any parameter (in long index) raises (Bounds) ; 

// Returns the indexed parameter from the receiving TypeCode. 

// Parameters are indexed from 0 to param_count ( ) -1 . 

// 

// The remaining operations are SOM-unique extensions. 

// 

short alignment (); 

// This operation returns the alignment required for an instance 
// of the type described by the receiving TypeCode. 

TypeCode copy (in TypeCode tc) ; 

// This operation returns a copy of the receiving TypeCode. 
void free (in TypeCode tc) ; 

// This operation frees the memory associated with the 
// receiving TypeCode. Subsequently, no further use can be 
// made of the receiver, which, in effect, ceases to exist. 




void print (in TypeCode tc) ; 

// This operation writes a readable representation of the 
// receiving TypeCode to stdout . Useful for examining 
// TypeCodes when debugging. 

void setAlignment (in short align) ; 

// This operation overrides the required alignment for an 
// instance of the type described by the receiving TypeCode. 

long size (in TypeCode tc) ; 

// This operation returns the size of an instance of the 
// type represented by the receiving TypeCode. 

} ; 



A detailed description of the programming interfaces for TypeCodes is given in the SOMobjects Deve/oper Too/Ait; Programmers Reference 
Manua/. 



Providing 'alignment' information 



In addition to the parameters in the TypeCodes that describe each type, a SOM-unique extension to the TypeCode functionality allows 
each TypeCode to carry alignment information as a "hidden" parameter. Use the TypeCode_alignment function to access the alignment 
value. The alignment value is a short integer that should evenly divide any memory address where an instance of the type will occur. 

If no alignment information is provided in your IDL source files, all TypeCodes carry default alignment information. The default alignment for 
a type is the natural boundary for the type, based on the natural boundary for the basic types of which it may be composed. This information 
can vary from one hardware platform to another. The TypeCode will contain the default alignment information appropriate to the platform 
where it was defined. 

To provide alignment information for the types and instances of types in your IDL source file, use the "align=N" modifier, where N is your 
specified alignment. Use standard modifier syntax of the SOM Compiler to attach the alignment information to a particular element in the IDL 
source file. In the following example, align=1 (that is, unaligned or no alignment) is attached to the struct "abc" and to one particular instance 
of struct "def" (the instance data item "y"). 

interface i { 

struct abc { 
long a; 
char b; 
long c; 

}; 

struct def { 
char 1; 
long m; 

}; 



void foo ( ) ; 

implementation { 

//# instance data 
abc x; 
def y ; 
def z ; 

//# alignment modifiers 
abc: align=l; 
y: align=l; 




Be aware that assigning the required alignment information to a type does not guarantee that instances of that type will actually be aligned 
as indicated. To ensure that, you must find a way to instruct your compiler to provide the desired alignment. In practice, this can be difficult 
except in simple cases. Most compilers can be instructed to treat all data as aligned (that is, default alignment) or as unaligned, by using a 
compile-time option or #pragma. The more important consideration is to make certain that the TypeCodes going into the Interface 
Repository actually reflect the alignment that your compiler provides. This way, when programs (such as the DSOM Framework) need to 
interpret the layout of data during their execution, they will be able to accurately map your data structures. This happens automatically when 
using the normal default alignment. 

If you wish to use unaligned instance data when implementing a class, place an "unattached" al±gn=l modifier in the implementation 




section. An unattached align=N modifier is presumed to pertain to the class's instance data structure, and will by implication be 
attached to all of the instance data items. 

When designing your own public types, be aware that the best practice of all (and the one that offers the best opportunity for language 
neutrality) is to lay out your types carefully so that it will make no difference whether they are compiled as aligned or unaligned! 



Using the 'tk foreign' TypeCode 



TypeCodes can be used to partially describe types that cannot be described in IDL (for example, a FILE type in C, or a specific class type in 
C++). The SOM-unique extension tk_foreign is used for this purpose. A tk_foreign TypeCode contains three parameters: 

1 . The name of the type, 

2. An implementation context string, and 

3. A length. 

The implementation context string can be used to carry an arbitrarily long description that identifies the context where the foreign type can 
be used and understood. If the length of the type is also known, it can be provided with the length parameter. If the length is not known or is 
not constant, it should be specified as zero. If the length is not specified, it will default to the size of a pointer. A tk_foreign TypeCode can 
also have alignment information specified, just like any other TypeCode. 

Using the following steps causes the SOM Compiler to create a foreign TypeCode in the Interface Repository: 

1 . Define the foreign type as a typedef SOMFOREIGN in the IDL source file. 

2. Use the #pragma modifier statement to supply the additional information for the TypeCode as modifiers. The implementation 
context information is supplied using the "impctx" modifier. 

3. Compile the IDL file using the -u option to place the information in the Interface Repository. 

For example: 

typedef SOMFOREIGN Point; 

♦pragma modifier Point: impctx="C++ Point class ", length=12 , align=4 ; 



If a foreign type is used to define instance data, structs, unions, attributes, or methods in an IDL source file, it is your responsibility to ensure 
that the implementation and/or usage bindings contain an appropriate definition of the type that will satisfy your compiler. You can use the 
passthru statement in your IDL file to supply this definition. Flowever, it is not recommended that you expose foreign data in attributes, 
methods, or any of the public types, if this can be avoided, because there is no guarantee that appropriate usage binding information can be 
provided for all languages. If you know that all users of the class will be using the same implementation language that your class uses, you 
may be able to disregard this recommendation. 



TypeCode constants 



TypeCodes are actually available in two forms: In addition to the TypeCode information provided by the methods of the Interface 
Repository, TypeCode constants can be generated by the SOM Compiler in your C or C++ usage bindings upon request. A TypeCode 
constant contains the same information found in the corresponding IR TypeCode, but has the advantage that it can be used as a literal in a 
C or C++ program anywhere a normal TypeCode would be acceptable. 

TypeCode constants have the form TC_< typename > , where <typename> is the name of a type (that is, a typedef, union, struct, or enum) 
that you have defined in an IDL source file. In addition, all IDL basic types and certain types dictated by the OMG CORBA standard come 
with pre-defined TypeCode constants (such as TCJong, TC_short, TC_char, and so forth). A full list of the pre-defined TypeCode 
constants can be found in the file "somtcnst.h''. You must explicitly include this file in your source program to use the pre-defined TypeCode 
constants. 

Since the generation of TypeCode constants can increase the time required by the SOM Compiler to process your IDL files, you must 
explicitly request the production of TypeCode constants if you need them. To do so, use the "tcconsts" modifier with the -m option of the sc 
or some command. For example, the command 



sc -sh -mtcconsts myclass.idl 
some -sh -mtcconsts myclass.idl 



(On AIX or Windows) 
(On Windows) 




will cause the SOM Compiler to generate a "myclass.h" file that contains TypeCode constants for the types defined in "myclass.idl". 



Using the IDL basic type 'any' 



Some Interface Repository methods and TypeCode functions return information typed as the IDL basic type any. Usually this is done when 
a wide variety of different types of data may need to be returned through a common interface. The type any actually consists of a structure 
with two fields: a _type field and a _value field. The _value field is a pointer to the actual datum that was returned, while the _type field 
holds a TypeCode that describes the datum. 

In many cases, the context in which an operation occurs makes the type of the datum apparent. If so, there is no need to examine the 
TypeCode unless it is simply as a consistency check. For example, when accessing the first parameter of a tk_struct TypeCode, the type 
of the result will always be the name of the structure (a string). Because this is known ahead of time, there is no need to examine the 
returned TypeCode in the any_type field to verify that it is a tk_string TypeCode. You can just rely on the fact that it is a string; or, you can 
check the TypeCode in the _type field to verify it, if you so choose. 

An IDL any type can be used in an interface as a way of bypassing the strong type checking that occurs in languages like ANSI C and C++. 
Your compiler can only check that the interface returns the any structure; it has no way of knowing what type of data will be carried by the 
any during execution of the program. Consequently, in order to write C or C++ code that accesses the contents of the any correctly, you 
must always cast the _value field to reflect the actual type of the datum at the time of the access. 

Flere is an example of a code fragment written in C that illustrates how the casting must be done to extract various values from an any: 

ftinclude <som.h> /* For "any" & "Environment" typedefs */ 

ftinclude <somtc.h> /* For TypeCode_kind prototype */ 

any result; 

Environment *ev; 

printf (" result ._value = "); 

switch (TypeCode_kind (result ._type, ev) ) { 

case tk_string: 

printf ("%s\n", *( (string *) result ._value) ) ; 
break ; 

case tk_long: 

printf ("%ld\n", * ( (long *) result ._value) ) ; 
break ; 

case tk_boolean: 

printf ("%d\n", *( (boolean *) result ._value) ) ; 
break ; 

case tk_float: 

printf ("%f\n", *( (float *) result ._value) ) ; 
break ; 

case tk_double: 

printf ("%f\n", *( (double *) result ._value) ) ; 
break ; 

default : 

printf ("something else!\n"); 

if 



Note: Of course, an any has no restriction, per se, on the type of datum that it can carry. Frequently, however, methods that return an any or 
that accept an any as an argument do place semantic restrictions on the actual type of data they can accept or return. Always consult the 
reference page for a method that uses an any to determine whether it limits the range of types that may be acceptable. 



The Metaclass Framework 



In SOM, classes are objects; metaclasses are classes and thus are objects, too. Also depicted are the three primitive class objects of the 




SOM run time: SOMCIass, SOMobject, and SOMCIassMgr. 

Primitive objects of the SOM run time 




The important point to be aware of here is that any class that is a subclass of SOMCIass is a metac/ass This chapter describes 
metaclasses that are available in SOMobjects Toolkit. There are two kinds of metaclasses: 

Framework metac/asses -metaclasses for building new metaclasses and Uti/ity metac/asses - metaclasses to help you write applications 
Briefly, the SOMobjects Toolkit provides the following metaclasses of each category for use by programmers: 

• Framework metaclasses: 

SOMMBeforeAfter Used to create a metaclass that has "before" and "after" methods for all methods (inherited or introduced) invoked on 
instances of its classes. 

• Utility metaclasses: 

SOMMSinglelnstance Used to create a class that may have at most one instance. 

SOMMTraced Provides tracing for every invocation of all methods on instances of its classes. 



The following sections describe each metaclass more fully. 
Class organization of the Metaclass Framework. 






A note about metaclass programming 



SOM metaclasses are carefully constructed so that they compose (see Section 8.1 below). If you need to create a metaclass, you can 
introduce new class methods, and new class variables, but you should not override any of the methods introduced by SOMCIass. If you 
need more than this, request access to the experimental Cooperative metaclass used to implement the Metaclass Framework metaclasses 
described in this chapter. 



Framework Metaclasses for "Before/After" Behavior 



This section covers the following subjects: 

• The 'SOMMBeforeAfter' metaclass 

• Composition of before/after metaclasses 

• Notes and advantages of 'before/after' usage 



The 'SOMMBeforeAfter' metaclass 



SOMMBeforeAfter is a metaclass that allows the user to create a class for which a particular method is invoked before each invocation of 
every method, nd for which a second method is invoked after each invocation. SOMMBeforeAfter defines two methods: 
sommBeforeMethod and sommAfterMethod. These two methods are intended to be overridden in the child of SOMMBeforeAfter to 
define the particular "before" and "after" methods needed for the client application. 

For example, suppose a "Barking" metaclass (a subclass of SOMMBeforeAfter overrides the sommBeforeMethod and 
sommAfterMethod with a method that emits one bark when invoked. Thus, one can create the "BarkingDog" class, whose instances (such 
as "Lassie") bark twice when "disturbed" by a method invocation. 



A hierarchy of metaclasses 






The SOMMBeforeAfter metaclass is designed to be subclassed; a subclass (or child) of SOMMBeforeAfter is also a metaclass. The 
subclass overrides sommBeforeMethod or sommAfterMethod or both. These (redefned) methods are invoked before and after any 
method supported by instances of the subclass (these methods are called primary methods). That is, they are invoked before and after 
methods invoked on the ordinary objects that are instances of the class objects that are instances of the subclass of SOMMBeforeAfter. 

The sommBeforeMethod returns a boolean value. This allows the "before" method to control whether the "after" method and the primary 
method get invoked. If sommBeforeMethod returns TRUE, normal processing occurs. If FALSE is returned, neither the primary method nor 
the corresponding sommAfterMethod is invoked. In addition, no more deeply nested before/after methods are invoked (see "Composition 
of before/after metaclasses" below). This facility can be used, for example, to allow a before/after metaclass to provide secure access to an 
object. The implication of this convention is that, if sommBeforeMethod is going to return FALSE, it must do any post-processing that might 
otherwise be done in the "after" method. 

Caution: somlnit and somFree are among the methods that get before/after behavior. This implies the following two obligations are 
imposed on the programmer of a SOMMBeforeAfter class. First, the implementation must guard against sommBeforeMethod being called 
before somlnit has executed, and the object is not yet fully initialized. Second, the implementation must guard against sommAfterMethod 
being called after somFree, at which time the object no longer exists (see the example "C implementation for 'Barking' metaclass" below). 

The following example shows the IDL needed to create a Barking metaclass. Just run the appropriate emitter to get an implementation 
binding, and then provide the appropriate "before" behavior and "after" behavior. 

SOM IDL for 'Barking' metaclass 

ftifndef Barking_idl 
#define Barking_idl 

ftinclude <sombacls . idl> 
interface Barking : SOMMBeforeAfter 
{ 

ftifdef SOMIDL 

implementation 

{ 

//# Class Modifiers 
filestem = barking; 
callstyle = idl; 

//# Method Modifiers 
sommBeforeMethod : override; 
sommAfterMethod : override; 

} ; 

#endif /* SOMIDL */ 

} ; 

#endif /* Barking_idl */ 





The next example shows an implementation of the Barking metaclass in which no barking occurs when somFree is invoked. 

C implementation for ’Barking' metaclass 

#define Barking_Class_Source 
#include <barking.ih> 

static char *somMN_somFree = "somFree"; 
static somld som!d_somFree = &somMN_somFree; 



SOM_Scope boolean SOMLINK sommBef oreMethod (Barking somSelf, 

Environment *ev, 
SOMObject object, 
somld methodld, 
va_list ap) 

{ 



if 



} 



( ! somComparelds ( 
print f ( "WOOF" ) ; 



methodld. 



som!d_somFree ) 



SOM_Scope void SOMLINK sommAf terMethod (Barking somSelf, 

Environment *ev, 
SOMObject object, 
somld methodld, 
somld descriptor, 
somToken returnedvalue, 
va_list ap) 

{ 



if 



} 



( ! somComparelds ( 
print f ( "WOOF" ) ; 



methodld. 



somId_somFree ) 



Composition of before/after metaclasses 



When there are two before/after metaclasses -"Barking" (as before) and "Fierce", which has a sommBeforeMethod and 
sommAfterMethod that both growl (that is, both methods make a "grrrr" sound when executed). The preceding discussion demonstrated 
how to create a "FierceDog " or a "BarkingDog ", but has not yet addressed the question of how to compose these properties of fierce and 
barking. Composab///ty means having the ability to easily create either a "FierceBarkingDog" that goes "grrr woof woof grrr " when it 
responds to a method call or a "BarkingFierceDog " that goes "woof grrr grrr woof" when it responds to a method call. 

Example for composition of before or after metaclasses. 




There are several ways to express such compositions. Figure 1 depicts SOM IDL fragments for three techniques in which composition can 
be indicated by a programmer. These are denoted as Technique 1 , Technique 2, and Technique 3, each of which creates a 





"FierceBarkingDog" class, named "FB-1", "FB-2", and "FB-3", respectively, as follows: 

• In Technique 1 , a new metaclass ("FierceBarking") is created with both the "Fierce” and "Barking" metaclasses as parents. An 
instance of this new metaclass (that is, "FB-1") is a "FierceBarkingDog" (assuming "Dog " is a parent). 

• In Technique 2, a new class is created which has parents that are instances of "Fierce" and "Barking" respectively. That is, 
"FB-2" is a "FierceBarkingDog" also (assuming "FierceDog" and "BarkingDog" do not further specialize "Dog"). 

• In Technique 3, "FB-3", which also is a "FierceBarkingDog", is created by declaring that its parent is a "BarkingDog" and that its 
explicit (syntactically declared) metaclass is "Fierce". 



TECHNIQUE 1 


TECHNIQUE 2 


TECHNIQUE 3 


interface 


interface 


interface 


FB-1 : Dog 


FB-2 :FierceDog, 


FB-3 : BarkingDog 


{ 


BarkingDog 

/ 


{ 


implementation 

{ 


i 

Implementation 


implemetation 

{ 


met aclass=FierceBar king; 


{ 


metaclass=Fierce 



Figure 1 .Three techniques for composing before/after metaclasses. 

Note that the explicit metaclass in the SOM IDL of "FB-1 " is its derived class, "FierceBarking". The derived metaclass of "FB-2" is also 
"FierceBarking". Lastly, the derived metaclass of "FB-3" is not the metaclass explicitly specified in the SOM IDL; rather, it too is 
"FierceBarking." 



Notes and advantages of 'before/after' usage 



Notes on the dispatching of before/after methods: 

• A before (after) method is invoked just once per primary method invocation. 

• The dispatching of before/after methods is thread-safe. 

• The dispatching of before/after methods is fast. The time overhead for dispatching a primary method is on the order of N times 
the time to invoke a before/after method as a procedure, where N is the total number of before/after methods to be applied. 

In conclusion, consider an example that clearly demonstrates the power of the composition of before/after metaclasses. Suppose you are 
creating a class library that will have n classes. Further suppose there are p properties that must be included in all combinations for all 
classes. Potentially, the library must have n2p classes. Let us hypothesize that (fortunately) all these properties can be captured by 
before/after metaclasses. In this case, the size of the library is n+p. 

The user of such a library need only produce those combinations necessary for a given application. In addition, note that there is none of the 
usual programming. Given the IDL for a combination of before/after metaclasses, the SOM compiler generates the implementation of the 
combination (in either C or C++) with no further manual intervention. 



The 'SOMMSinglelnstance' Metaclass 




Sometimes it is necessary to define a class for which only one instance can be created. This is easily accomplished with the 
SOMMSinglelnstance metaclass. Suppose the class "Collie" is an instance of SOMMSinglelnstance. The first call to CollieNew creates 
the one possible instance of "Collie"; hence, subsequent calls to CollieNew return the first (and only) instance. 

Any class whose metaclass is SOMMSinglelnstance gets this requisite behavior; nothing further needs to be done. The first instance 
created is always returned by the < c/ass A/ame>Hew maro. 

Alternatively, the method sommGetSinglelnstance does the same thing as the < c/ass A/ame>Ue\N macro. This method invoked on a class 
object (for example, "Collie") is useful because the call site explicitly shows that something special is occurring and that a new object is not 
necessarily being created. For this reason, one might prefer the second form of creating a single-instance object to the first. 

Instances of SOMMSinglelnstance keep a count of the number of times somNew and sommGetSinglelnstance are invoked. Each 
invocation of somFree decrements this count. An invocation of somFree does not actually free the single instance until the count reaches 
zero. 

SOMMSinglelnstance overrides somRenew, somRenewNolnit, somRenewNolnitNoZero, and somRenewNoZero so that a proxy is 
created in the space indicated in the somRenew* call. This proxy redispatches all methods to the single instance, which is always allocated 
in heap storage. Note that all of these methods (somRenew*) increment the reference count; therefore, somFree should be called on these 
objects, too. In this case, somFree decrements the reference and frees the single instance (and, of course, takes no action with respect to 
the storage indicated in the original somRenew* call). 

If a class is an instance of SOMMSinglelnstance, all of its subclasse are also instances of SOMMSinglelnstance. Be aware that this also 
means that each subclass is allowed to have only a single instance. (This may seem obvious. Flowever, it is a common mistake to create a 
framework class that must have a single instance, while at the same time expecting users of the framework to subclass the single instance 
class. The result is that two single-instance objects are created: one for the framework class and one for the subclass. One technique that 
can mitigate this scenario is based on the use of somSubstituteClass. In this case, the creator of the subclass must substitute the subclass 
for the framework class - before the instance of the framework class is created.) 



The 'SOMMTraced' Metaclass 



SOMMTraced is a metaclass that facilitates tracing of method invocations. If class ''Collie 1 ' is an instance of SOMMTraced (if SOMMTraced 
is the metaclass of "Collie"), any method invoked on an instance of "Collie" is traced. That is, before the method begins execution, a 
message prints (to standard output) giving the actual parameters. Then, after the method completes execution, a second message prints 
giving the returned value. This behavior is attained merely by being an instance of the SOMMTraced metaclass. 

If the class being traced is contained in the Interface Repository, actual parameters are printed as part of the trace. If the class is not 
contained in the Interface Repository, an ellipsis is printed. 

To be more concrete, suppose that the class "Collie" is a child of "Dog" and is an instance of SOMMTraced. Because SOMMTraced is the 
metaclass of "Collie," any method invoked on "Lassie" (an instance of "Collie") is traced. 

It is easy to use SOMMTraced: Just make a class an instance of SOMMTraced in order to get tracing. 

There is one more step for using SOMMTraced: Nothing prints unless the environment variable SOMM_TRACED is set. If it is set to the 
empty string, all traced classes print. If SOMM_TRACED is not the empty string, it should be set to the list of names of classes that should 
be traced. For example, the following command turns on printing of the trace for "Collie", but not for any other traced class: 

export SOMM_TRACED=Collie (on AIX) 

SET SOMM_TRACED=Collie (on OS/2 or Windows) 



The example below shows the IDL needed to create a traced dog class: Just run the appropriate emitter to get an implementation binding. 

SOM IDL for 'TracedDog' class 

((include "dog.idl" 

((include <somtrcls . idl> 
interface TracedDog : Dog 
{ 

(tifdef SOMIDL 

implementation 

{ 

//# Class Modifiers 
filestem = trdog; 
metaclass = SOMMTraced; 

} ; 

(tendif /* SOMIDL */ 




Error Codes 



It is possible to receive the following messages from the Metaclass Framework while an application is running. 

60001 An attempt was made to construct a class with SOMMSinglelnstance as a metaclass constraint. (This may occur 
indirectly because of the construction of a derived metaclass). The initialization of the class failed because 
somlnitMICIass defined by SOMMSinglelnstance is in conflict with another metaclass that has overridden 
somNew. That is, some other metaclass has already claimed the right to return the value for somNew. 

60002 An attempt was made to construct a class with SOMMSinglelnstance as a metaclass constraint. (This may occur 
indirectly because of the construction of a derived metaclass). The initialization of the class failed because 
somlnitMICIass defined by SOMMSinglelnstance is in conflict with another metaclass that has overridden 
somFree. That is, some other metaclass has already claimed this right to override somFree. 

60004 An invocation of somrRepInit was made with a logging type other than 'o' or V. 

60005 The sommBeforeMethod or the sommAfterMethod was invoke on a SOMRReplicbleObject whose logging type is 
other than 'o' or 'v'. This error cannot occur normally. The likely cause is that some method invoked on another object 
has overwritten this object's memory. 

60006 A Before/After Metaclass must override both sommBeforeMethod an sommAfterMethod. This message indicates 
an attempt to create a Before/After Metaclass where only one of the above methods is overridden. 



The Event Management Framework 



The Event Management Framework is a central facility for registering all events of an application. Such a registration facilitates grouping of 
various application events and waiting on multiple events in a single event-processing loop. This facility is used by the Replication 
Framework and by DSOM to wait on their respective events of interest. The Event Management Framework must also be used by any 
interactive application that contains DSOM or replicated objects. 



Event Management Basics 



The Event Management Framework consists of an Event Manager (EMan) class, a Registration Data class and several Event classes. It 
provides a way to organize various application events into groups and to process all events in a single event-processing loop. The need for 
this kind of facility is seen very clearly in interactive applications that also need to process some background events (say, messages arriving 
from a remote process). Such applications must maintain contact with the user while responding to events coming from other sources. 

One solution in a multi-threaded environment is to have a different thread service each different source of events. For a single-threaded 
environment it should be possible to recognize and process all events of interest in a single main loop. EMan offers precisely this capability. 
EMan can be useful even when multiple threads are available, because of its simple programming model. It avoids contention for common 
data objects between EMan event processing and other main-loop processing activity. 



Model of EMan usage 



The programming model of EMan is similar to that of many GUI toolkits. The main program initializes EMan and then registers interest in 
various types of events. The main program ends by calling a non-returning function of EMan that waits for events and dispatches them as 
and when they occur. In short, the model includes steps that: 




1 . Initialize the Event Manager, 

2. Register with EMan for all events of interest, and 

3. Hand over control to EMan to loop forever and to dispatch events. 

The Event Manager is a SOM object and is an instance of the SOMEEMan class. Since any application requires only one instance of this 
object, the SOMEEMan class is an instance of the SOMMSinglelnstance class. Creation and initialization of the Event Manager is 
accomplished by a function call to SOMEEmanNew. 

Currently, EMan supports the four kinds of events described in the following topic. An application can register or unregister for events in a 
callback routine (explained below) even after control has been turned over to EMan. 



Event types 



Event types are categorized as follows: 

• Timer events 

These can be either one-time timers or interval timers. 

• Sink events (sockets, file descriptors, and message queues) 

On AIX, this includes file descriptors for input/output files, sockets, pipes, and message queues. On OS/2 and Windows, only 
TCP/IP sockets are supported. 

Note:On OS/2 and Windows, the Sockets classes for NetBIOS (NBSockets) and Novell IPX/SPX (IPXSockets) are primarily 
intended for use by DSOM and the Replication Framework, not for general application programming. (The Replication 
Framework is available as part of the full-capability SOMobjects Developer Toolkit.) 

• Client events (any event that the application wants to queue with EMan) 

These events are defined, created, processed, and destroyed by the application. EMan simply acts as a place to queue these 
events for processing. EMan dispatches these client events whenever it sees them. Typically, this happens immediately after the 
event is queued. 

• Work procedure events (procedures that can be called when there is no other event) 

These are typically background procedures that the application intends to execute when there are spare processor cycles. When 
there are no other events to process, EMan calls all registered work procedures. A work procedure event is called only after all 
other higher priority events have been called. A work procedure event is not called if there are no other events to be processed. 

The Event Management Framework is extendible (that is, other event types can be added to it) through subclassing. The event types 
currently supported by EMan are at a sufficiently low level so as to enable building other higher level application events on top of them. For 
example, you can build an X-event handler by simply registering the file descriptor for the X connection with EMan and getting notified when 
any X-event occurs. 



Registration 



This topic illustrates how to register for an event type. 



Callbacks 



The programmer decides what processing needs to be done when an event occurs and then places the appropriate code either in a 
procedure or in a method of an object. This procedure or method is called a callback. (The callback is provided to EMan at the time of 
registration and is called by EMan when a registered event occurs.) The signature of a callback is fixed by the framework and must have 
one of the following three signatures: 




void SOMLINK EMRegProc (SOMEEvent , void *) ; 

void SOMLINK EMMethodProc (SOMOb ject , SOMEEvent , void *) ; 

void SOMLINK EMMethodProcEv (SOMOb ject , Environment *Ev, 

SOMEEvent, void *) ; 

/* On OS/2, they all use "system" linkage */ 

/* On Windows, the SOMLINK keyword is Not included if the 
* application is intended to support multiple instances. */ 



The three specified prototypes correspond to a simple callback procedure, a callback method using OIDL call style, and a callback method 
using IDL call style. The parameter type SOMEEvent refers to an event object passed by EMan to the callback. Event objects are described 
below. 

NOTE: When the callbacks are methods, EMan calls these methods using Name-lookup Resolution (see Chapter 5 Section 5.3 on Method 
Resolution). One of the implications is that at the time of registration EMan queries the target object's class object to provide a method 
pointer for the method name supplied to it. Eman uses this pointer for making event callbacks. 



Event classes 



All event objects are instances of either the SOMEEvent class or a subclass of it. The hierarchy of event classes is as follows: 

SOMObject SOMEEvent SOMETimerEvent 

SOMEClient Event 

SOMESinkEvent 

SOMEWorkProcEvent 



When called by EMan, a callback expects the appropriate event instance as a parameter. For example, a callback registered for a timer 
event expects a SOMETimerEvent instance from EMan. 



EMan parameters 



Several method calls in the Event Management Framework make use of bit masks and constants as parameters (for example, 
EMSinkEvent or EMInputReadMask). These methods are defined in the include file "eventmsk.h". When a user plans to extend the Event 
Management Framework, care must be taken to avoid name and value collisions with the definitions in "eventmsk.h". For convenience, the 



contents of the "eventmsk.h" file are shown below. 

#ifndef H_EVENTMASKDEF 
#def ine H_EVENTMASKDEF 

/* Event Types */ 

#define EMTimerEvent 54 

#define EMSignalEvent 55 

#define EMSinkEvent 56 

#define EMWorkProcEvent 57 

#define EMClientEvent 58 

#define EMMsgQEvent 59 

/* Sink input/output condition mask */ 

#define EMInputReadMask (1L<0) 

#define EMInputWriteMask (1L<1) 

#define EMInputExceptMask (1L<2) 

/* Process Event mask */ 

#define EMProcessTimerEvent (1L<0) 




#define EMProcessSinkEvent (1L<1) 
#define EMProcessWorkProcEvent (1L<2) 
#define EMProcessClientEvent (1L<3) 
#define EMProcessAllEvents (1L<6) 



#endif /* H_EVENTMASKDEF */ 



Registering for events 



In addition to the event classes, the Event Management Framework uses a registration data class (SOMEEMRegisterData) to capture all 
event-related registration information. The procedure for registering interest in an event is as follows: 

1 . Create an instance of the SOMEEMRegisterData class (this will be referred to as a "RegData" object). 

2. Set the event type of "RegData.” 

3. Set the various fields of "RegData" to supply information about the particular event for which an interest is being registered. 

4. Call the registration method of EMan, using "RegData" and the callback method information as parameters. The callback 
information varies, depending upon whether it is a simple procedure, a method called using OIDL call style, or a method called 
using IDL call style. 

The following code segment illustrates how to register input interest in a socket "sock" and provide a callback procedure "ReadMsg". 

data = SOMEEMRegisterDataNew ( ); /* create a RegData object */ 

_someClearRegData (data, Ev) ; 

_someSetRegDataEventMask (data, Ev, EMSinkEvent, NULL) ; /* Event type */ 

_someSetRegDataSink (data, Ev, sock); /* provide the socket id */ 

_someSetRegDataSinkMask (data, Ev, EMinputReadMask ); 

/*input interest */ 

regid = _someRegisterProc (some_gEMan, Ev, data, ReadMsg, "UserData" ) ; 

/* some_gEMan points to EMan. The last parameter "userData" is any 
data the user wants to be passed to the callback procedure as a 
second parameter */ 



Unregistering for events 



One can unregister interest in a given event type at any time. To unregister, you must provide the registration id returned by EMan at the 
time of registration. Unregistering a non-existent event (such as, an invalid registration id) is a no-op. The following example unregisters the 
socket registered above: 

_someUnRegister (some_gEMan, Ev, regid); 



An example callback procedure 



The following code segment illustrates how to write a callback procedure: 

void SOMLINK ReadMsg ( SOMEEvent event, void *targetData ) 

{ 

int sock; 

printf ( "Data = %s\n", targetData ); 
switch! _somevGetEventType ( event )) { 




case EMSinkEvent: 

printf ( "callback : Perceived Sink EventAn"); 
sock = _somevGetEventSink (event ) ; 

/* code to read the message off the socket */ 
break; 

default: printf ( "Unknown Event type in socket callback\n" ) ; 



/* On OS/2, "system" linkage is also required. */ 

/* On Windows, callbacks do not use the SOMLINK keyword if 
* the application is intended to support multiple instances. */ 



Generating client events 



While the other events are caused by the operating system (for example, Timer), by I/O devices, or by external processes, client events are 
caused by the application itself. The application creates these events and enqueues them with EMan. When client events are dispatched, 
they are processed in a callback routine just like any other event. The following code segment illustrates how to create and enqueue client 
events. 

clientEventl = SOMEClientEventNew ( ) ; /* create a client event */ 

_somevSetEventClientType ( clientEventl, Ev, "MyClientType" ); 

_somevSetEventClientData ( clientEventl, Ev, 

"I can give any data here"); 

/* assuming that "MyClientType" is already registered with EMan */ 

/* enqueue the above event with EMan */ 

_someQueueEvent (some_gEMan, Ev, clientEventl); 



Examples of using other events 



The sample program shipped with the Event Management Framework illustrates the tasks listed below. (Due to its large size, the source 
code is not included here.) 

• Registering and unregistering for Timer events. 

• Registering and unregistering for Workproc events. 

• Registering an AIX Message Queue, sending messages on it, and unregistering the Message Queue. 

• Registering a stream socket that listens to incoming connection requests. Also, sockets connecting, accepting a connection, and 
sending/receiving messages through EMan. 

• Registering a file descriptor on AIX and reading one line of the file at a time in a callback. 



Processing events 



After all registrations are finished, an application typically turns over control to EMan and is completely event driven thereafter. Typically, an 
application main program ends with the following call to EMan: 

_someProcessEvents (some_gEMan, Ev) ; 



An equivalent way to process events is to write a main loop and call someProcessEvent from inside the main loop, as indicated: 




while (1) { /* do forever */ 

_someProcessEvent ( some_gEMan, Ev, EMProcessTimerEvent E 

EMProcessSinkEvent E 
EMProcessClientEvent E 
EMProcessWorkProcEvent ) ; 
/*** Do other main loop work, as needed. ***/ 

} 



The second way allows more precise control over what type of events to process in each call. The example above enables all four types to 
be processed. The required subset is formed by logically OR'ing the appropriate bit constants (these are defined in "eventmsk.h)". Another 
difference is that the second way is a non-blocking call to EMan. That is, if there are no events to process, control returns to the main loop 
immediately, whereas someProcessEvents is a non-returning blocking call. For most applications, the first way of calling EMan is better, 
since it does not waste processor cycles when there are no events to process. 



Interactive applications 



Interactive applications need special attention when coupled with EMan. Once control is turned over to EMan by calling 
someProcessEvents, a single-threaded application (for example, on AIX) has no way of responding to keyboard input. The user must 
register interest in "stdin" with EMan and provide a callback function that handles keyboard input. In a multi-threaded environment (for 
example, OS/2), this problem can be solved by spawning a thread to execute someProcessEvents and another to handle keyboard input. 
(These two options are illustrated in the sample program shipped with the Event Management Framework.) 



Event Manager Advanced Topics 



This section contains the following subjects: 

• Threads and thread safety 

• Writing an X or MOTIF application 

• Extending EMan 

• Using EMan from C++ 

• Using EMan from other languages 

• Tips on using EMan 



Threads and thread safety 



As indicated earlier, on OS/2, interactive programs call someProcessEvents in one thread and process keyboard input in a separate 
thread. (This recommended usage is illustrated in the sample program). The event manager object (EMan) is thread safe in the sense that 
concurrent method invocations on EMan are serialized. Even when someProcessEvents is invoked in a thread and other methods of EMan 
are invoked from other threads, EMan still preserves its data integrity. Flowever, when Eman dispatches an event, a callback can call 
methods on the same data objects as the other interactive thread(s). The user must protect such data objects using appropriate concurrency 
control techniques (for example by using semaphores). 

One must also be aware of some deadlock possibilities. Consider the following situation. EMan code holds some SOMobjects Toolkit 
semaphores while it is running (for example, while in someProcessEvents). A user-defined object protects its data by requiring its methods 
to acquire and release a sempahore on the object. If a separate thread running in this object were to call an operation that requires a 
SOMobjects Toolkit semaphore (which is currently held by EMan) and if concurrently EMan dispatches an event whose callback invokes a 
method of this object, a deadlock occurs. Two possibilities exist to cope with such a situation: One is to acquire all needed semaphores 
ahead of time, and the other is to abort the operation when you fail to obtain a semaphore. To achieve mutual exclusion with EMan, you can 
call the methods someGetEManSem and someReleaseEmanSem. These methods acquire and release the SOMobject Developer Toolkit 
semaphores that EMan uses. 



Writing an X or MOTIF application 




Although the Event Manager does not recognize X events, an X or MOTIF application can be integrated with EMan as follows. First, the 
necessary initialization of X or MOTIF should be performed. Next, using the Xlib macro "ConnectionNumber" or the "XConnectionNumber" 
function, you can obtain the file descriptor of the X connection. This file descriptor can be registered with EMan as a sink. It can be 
registered for both input events and exception events. When there is any activity on this X file descriptor, the developer-provided callback is 
invoked. The callback can receive the X-event, analyze it, and do further dispatching. See the example program in Chapter 9, "The 
Replication Framework" (section 9.7). 



Extending EMan 



The current event manager can be extended without having access to the source code. The use of EMan in an X or MOTIF application 
mentioned above is just one such example. Several other extensions are possible. For example, new event types can be defined by 
subclassing either directly from SOMEEvent class or from any of its subclasses in the framework. There are three main problems to solve in 
adding a new event type: 

• Flow to register a new event type with EMan? 

• Flow to make EMan recognize the occurrence of the new event? 

• Flow to make EMan create and send the new event object (a subclass of SOMEEvent) to the callback when the event is 
dispatched? 

Because the registration information is supplied with appropriate "set" methods of a RegData object, the RegData object should be extended 
to include additional methods. This can be achieved by subclassing from SOMEEMRegisterData and building a new registration data class 
that has methods to "set" and "get" additional fields of information that are needed to describe the new event types fully. To handle 
registrations with instances of new registration data subclass, we must also subclass from SOMEEMan and override the someRegister and 
the someUnRegister methods. These methods should handle the information in the new fields introduced by the new registration data class 
and call parent methods to handle the rest. 

Making EMan recognize the occurrence of the new event is primarily limited by the primitive events EMan can wait on. Thus the new event 
would have to be wrapped in a primitive event that EMan can recognize. For example, to wait on a message queue on OS/2 concurrently 
with other EMan events, a separate thread can be made to wait on the message queue and to enqueue a client event with EMan when a 
message arrives on this message queue. We can thus bring multiple event sources into the single EMan main loop. 

The third problem of creating new event objects unknown to EMan can be easily done by applying the previous technique of wrapping the 
new event in terms of a known event. In a callback routine of the known event, we can create and dispatch the new event unknown to 
EMan. Of course, this does introduce an intermediate callback routine which would not be needed if EMan directly understood the new 
event type. 

A general way of extending EMan is to look for newly defined event types by overriding someProcessEvent and someProcessEvents in a 
subclass of EMan. 



Using EMan from C++ 



The Event Management framework can be used from C++ just like any other framework in the SOMobjects Toolkit. You must ensure that 
the C++ usage bindings (that is, the .xh files) are available for the Event Management Framework classes. These .xh files are generated by 
the SOM Compiler in the SOMobjects Toolkit when the -s option includes an xh emitter. 



Using EMan from other languages 



The event manager and the other classes can be used from other languages, provided usage bindings are available for them. These usage 
bindings are produced from .idl files of the framework classes by the appropriate language emitter. 



Tips on using EMan 




The following are some do's and don'ts for EMan: 



Eman callback procedures or methods must return quickly. You cannot wait for long periods of time to return from the callbacks. 

If such long delays occur, then the application may not notice some subsequent events in time to process them meaningfully (for 
example, a timer event may not be noticed until long after it occurred). 

It follows from the previous tip that you should not do independent "select" system calls on file descriptors while inside a 
callback. (This applies to sockets and message queues, as well.) In general, a callback should not do any blocking of system 
calls. If an application must do this, then it must be done with a small timeout value. 

Since EMan callbacks must return quickly, no callback should wait on a semaphore indefinitely. If a callback has to obtain some 
semaphores during its processing, then the callback should try to acquire all of them at the very beginning, and should be 
prepared to abort and return to EMan if it fails to acquire the necessary semaphores. 

EMan callback methods are called using name-lookup resolution. Therefore, the parameters to an EMan registration call must be 
such that the class object of the object parameter must be able to provide a pointer to the method indicated by the method 
parameter. Although this requirement is satisfied in a majority of cases, there are exceptions. For example, if the object is a 
proxy (in the DSOM sense) to a remote object, then the "real" class object cannot provide a meaningful method pointer. Also 
note that, when somDspatch is overridden, the effect of such an override will not apply to the callback from EMan. Do not use a 
method callback in these situations; instead, use a procedure callback. 



Limitations 



The present implementation of the Event Management framework has the limitations described below. For a more up-to-date list of 
limitations, refer to the README file on EMan in the SOMobjects Developer Toolkit. 

• EMan supports registering a maximum of 64 AIX message queues. 

• EMan can only wait on file descriptors (including files, pipes, sockets, and message queues) on AIX, and socket identifiers on 
OS/2. 

• EMan supports registering a maximum of FILENO (the AIX limit on maximum number of open files) file descriptors on AIX, and 
FD_SETSIZE socket identifiers on OS/2 (FD_SETSIZE is defined by the TCP/IP product). 



Use of EMan DLL 



The Event Manager Framework uses a Sockets "select" call to wait on multiple sockets. At the time of EMan creation, the SOMEEMan 
class object loads one of the Sockets subclass DLLs, based on the value of the environment variable SOMSOCKETS. This environment 
variable should name the implementation class of sockets (see Appendix E describing the Sockets abstract class and the specific 
implementation DLLs available with the SOMobjects Toolkit.) The current choices for this environment variable are TCPIPSockets, (and 
TCPIPSockets32 for OS/2), NBSockets, and IPXSockets . 



SOMobjects Error Codes 



This section covers the following subjects: 

• SOM Kernel Error Codes 

• DSOM Error Codes 

• Metaclass Framework Error Codes 



SOM Kernel Error Codes 



Following are error codes with messages/explanations for the SOM kernel and the various frameworks of the SOMobjects Developer 
Toolkit. 

Value Symbolic Name and Description 

20011 SOMERROR_CCNullClass 

The somDescendedFrom method was passed a null class argument. 

20029 SOMERROR_SompntOverf low 

The internal buffer used in somPrintf overflowed. 

20039 SOME RROR_MethodNot Found 

somFindMethodOk failed to find the indicated method. 

20049 SOMERROR_StaticMethodTableOverf low 

A Method-table overflow occurred in somAddStaticMethod. 

20059 SOMERROR_Def aultMethod 

The somDefaultMethod was called; a defined method probably was not added before it was invoked. 

20069 SOMERROR_MissingMethod 

The specified method was not defined on the target object. 

20079 SOME RROR_BadVers ion 

An attempt to load, create, or use a version of a class-object implementation is incompatible with the using program. 

20089 SOMERROR_NullId 

The SOM_Checkld was given a null ID to check. 

20099 SOMERROR_OutOfMemory 

Memory is exhausted. 

20109 SOMERROR_TestOb jectFailure 

The somObjectTest found problems with the object it was testing. 

20119 SOMERROR_FailedTest 

The somTest detected a failure; generated only by test code. 

20121 SOME RROR_Cl as sNot Found 

The somFindClass could not find the requested class. 

20131 SOME RROR_01dMet hod 

An old-style method name was used; change to an appropriate name. 

20149 SOMERROR_CouldNotStartup 

The somEnvironmentNew failed to complete. 

20159 SOMERROR_NotRegistered 

The somllnloadClassFile argument was not a registered class. 

20169 SOMERROR_BadOverride 

The somOverrideSMethod was invoked for a method that was not defined in a parent class. 

20179 SOMERROR_NotImplementedYet 

The method raising the error message is not implemented yet. 

20189 SOMERROR_MustOverride 

The method raising the error message should have been overridden. 

20199 SOMERROR_BadArgument 

An argument to a core SOM method failed a validity test. 



20219 



SOMERROR_NoParentClass 

During the creation of a class object, the parent class could not be found. 




20229 



SOMERROR_NoMetaClass 

During the creation of a class object, the metaclass object could not be found. 



DSOM Error Codes 



The following table lists the error codes that may be encountered when using DSOM. 



Value 


Description 


30001 


SOMDERROR_NoMemory 

Memory is exhausted. 


30002 


SOMDERROR_Not Implemented 

Function or method has a null implementation. 


30003 


SOMDERROR_UnexpectedNULL 

Internal error: a pointer variable was found to be NULL, unexpectedly. 


30004 


SOMDERROR_IO 

I/O error while accessing a file located in SOMDDIR. 


30005 


SOMDERROR_BadVersion 

Internal error: incorrect version of an object reference data table. 


30006 


SOMDERROR_ParmSize 

Internal error: a parameter of incorrect size was detected. 


30007 


SOMDERROR_HostName 

Communications error: unable to retrieve local host name. 


30008 


SOMDERROR_Host Address 

Communications error: unable to retrieve local host address. 


30009 


SOMDERROR_Socket Create 

Communications error: unable to create socket. 


30010 


SOMDERROR_SocketBind 

Communications error: unable to bind address to socket. 


30011 


SOMDERROR_SocketName 

Communications error: unable to query socket information. 


30012 


SOMDERROR_Socket Receive 

Communications error: unable to receive message from socket. 


30013 


SOMDERROR_SocketSend 

Communications error: indicates socket error. 


30014 


SOMDERROR_Socket Ioctl 

Communications error: unable to set socket blocking state. 


30015 


SOMDERROR_Socket Select 

Communications error: unable to select on socket. 


30016 


SOMDERROR_Packet Sequence 

Communications error: unexpected message packet received. 


30017 


SOMDERROR_PacketTooBig 

Communications error: packet too big for allocated message space. 


30018 


SOMDERROR_AddressNot Found 

Uninitialized DSOM communications object. 




30019 


SOMDERROR_NoMes sages 

No messages available (and caller specified "no wait' 


30020 


SOMDERROR_UnknownAddress 

Invalid client or server address. 


30021 


SOMDERROR_RecvError 

Communications error during receive. 


30022 


SOMDERROR_SendError 

Communications error in sending the request. 


30023 


SOMDERROR_CommT imeOut 

Communications timeout. 


30024 


SOMDERROR_Cannot Connect 

Unable to initialize connection information. 


30025 


SOMDERROR_BadConnection 

Invalid connection information detected. 


30026 


SOMDERROR_NoHostName 

Unable to get host name. 


30027 


SOMDERROR_BadBinding 

Invalid server location information in proxy object. 


30028 


SOMDERROR_BadMethodName 

Invalid method name in request message. 


30029 


SOMDERROR_BadEnvironment 

Invalid Environment value in request message. 


30030 


SOMDERROR_BadContext 

Invalid Context object in request message. 


30031 


SOMDE RROR_B a dNVL i s t 

Invalid Named Value List (NVList). 


30032 


SOMDERROR_BadFlag 

Bad flag in NVList item. 


30033 


SOMDERROR_BadLength 

Bad length in NVList item. 


30034 


SOMDERROR_BadOb j r e f 

Invalid object reference. 


30035 


SOMDERROR_NullField 

Unexpected null field in request message. 


30036 


SOMDERROR_UnknownRepo s I d 

Attempt to use Invalid Interface Repository ID. 


30037 


SOMDERROR_NVLi st Access 

Invalid NVList object in request message. 


30038 


SOMDERROR_NVIndexError 

Attempt to use an out-of-range NVList index. 


30039 


S OMD E RROR_S y s T i me 

Error retrieving system time. 


30040 


SOMDERROR_SystemCallFailed 

System call failed. 


30041 


SOMDERROR_CouldNotStartProcess 

Unable to start a new process. 




30042 

30043 

30044 

30045 

30046 

30047 

30048 

30049 

30050 

30051 

30052 

30053 

30054 

30055 

30056 

30057 

30058 

30059 

30060 

30061 

30062 

30063 

30064 



SOMDERROR_No Server Cl ass 

No SOMDServer (sub)class specified for server implementation. 

SOMDERROR_NoSOMDInit 

Missing SOMDJnit call in program. 

SOMDERROR_SOMDDIRNotSet 

SOMDDIR environment variable not set. 

SOMDERROR_No ImplDat abase 

Could not open Implementation Repository database. 

SOMDERROR_ImplNot Found 

Implementation not found in implementation repository. 

SOMDERROR_Cl as sNot Found 

Class not found in implementation repository. 

SOMDERROR_ServerNot Found 

Server not found in somdd's active server table. 

SOMDERROR_ServerAlreadyExists 

Server already exists in somdd's active server table. 

SOMDERROR_ServerNot Active 

Server is not active. 

SOMDERROR_CouldNot Start SOM 

SOM initialization error. 

SOMDERROR_Ob jectNot Found 

Could not find desired object. 

SOMDERROR_NoParentClass 

Unable to find / load parent class during proxy class creation. 

SOMDERROR_DispatchError 

Unable to dispatch method. 

SOMDERROR_BadTypeCode 

Invalid type code. 

SOMDERROR_BadDe script or 

Invalid method descriptor. 

SOMDERROR_BadRe suit Type 

Invalid method result type. 

SOMDERROR_Key InUse 

Internal object key is in use. 

SOMDERROR_KeyNot Found 

Internal object key not found. 

SOMDERROR_CtxInvalidPropName 

Illegal context property name. 

SOMDERROR_CtxNoPropFound 

Could not find property name in context. 

SOMDERROR_CtxSt art ScopeNot Found 

Could not find specified context start scope. 

SOMDERROR_CtxAccess 

Error accessing context object. 

SOMDERROR_CouldNot St art Thread 

System error: Could not start thread. 




30065 

30066 

30067 

30068 

30069 

30070 

30071 

30072 

30073 

30074 

30075 

30076 

30077 

30078 

30079 

30080 

30081 

30082 

30083 

30084 

30085 

30086 

30087 



SOMDERROR_AccessDenied 

System error: Access to a system resource (file, queue, shared memory, etc.) denied. 

S OMD E RROR_B a dP a r m 

System error: invalid parameter supplied to a operating system call. 

SOMDERROR_Interrupt 

System error: Interrupted system call. 

SOMDERROR_Locked 

System error: Drive locked by another process. 

SOMDERROR_Po inter 

System error: Invalid physical address. 

SOMDERROR_Boundary 

OS/2 system error: ERROR_CROSSES_OBJECT_BOUNDARY. 

SOMDERROR_UnknownError 

System error: Unknown error on operating system call. 

SOMDERROR_No Space 

System error: No space left on device. 

SOMDERROR_DuplicateQueue 

System error: Duplicate queue name. 

SOMDERROR_BadQueueName 

System error: Invalid queue name. 

SOMDERROR_DuplicateSem 

System error: Duplicate semaphore name used. 

SOMDERROR_BadSemName 

System error: Invalid semaphore name. 

SOMDERROR_TooManyHandles 

System error: Too many files open (no file handles left). 

SOMDERROR_BadAddrFamily 

System error: Invalid address family. 

SOMDERROR_BadFormat 

System error: Invalid format. 

SOMDERROR_BadDrive 

System error: Invalid drive. 

SOMDERROR_SharingViolation 

System error: Sharing violation. 

SOMDERROR_BadExe Signature 

System error: Program file contains a DOS mode program or invalid program. 

SOMDERROR_BadExe 

Executable file is invalid (linker errors occurred when program file was created). 

SOMDERROR_Busy 

System error: Segment is busy. 

SOMDERROR_BadThread 

System error: Invalid thread id. 

SOMDERROR_SOMDPORTNot Defined 

SOMDPORT not defined. 

SOMDERROR_ResourceExists 

System resource (file, queue, shared memory segment,, etc.) already exists. 




30088 

30089 

30090 

30091 

30092 

30093 

30096 

30097 

30098 

30105 

30106 

30107 

30108 

30110 

30111 

30112 

30113 

30114 

30115 

30117 

30118 

30119 

30120 



SOMDERROR_UserName 

USER environment variable is not set. 

SOMDERROR_WrongRef Type 

Operation attempted on an object reference is incompatible with the reference type. 

SOMDERROR_MustOverride 

This method has no default implementation and must be overridden. 

SOMDERROR_No Sockets Cl ass 

Could not find/load Sockets class. 

SOMDERROR_EManRegData 

Unable to register DSOM events with the Event Manager. 

SOMDERROR_NoRemoteComm 

Remote communications is disabled (for Workstation DSOM). 

SOMDERROR_GlobalAtomError 

On Windows only, an error occurred while adding a segment name to the Windows atom table. 
SOMDERROR_NamedMemoryTableError 

On Windows only, an error occurred while creating or deleting a (named) shared memory segment. 
SOMDERROR_WMQUIT 

On Windows only, indicates DSOM received a Windows WM_QUIT message. The developer of a server application 
should check for SOMDERROR_WMQUIT returned from method execute_request_loop and handle the error by 
cleaning up and exiting. 

SOMDERROR_DuplicatelmplEntry 

Implementation repository identifier already exists. Add wait time between 'regimpl' calls. 

SOMDERRORJnvalidSOMSOCKETS 
SOMSOCKETS environment variable set incorrectly. 

SOMDERRORJRNotFound 
Interface Repository not found. 

SOMDERR0R_ClassNotlnlR 

Attempt to create an object whose Class is not in the Interface Repository. 

SOMDERROR_SocketError 

A communications socket error has occurred. Make sure the DSOM daemon is running. 

SOMDERROR_PacketError 
A communications packet error has occurred. 

SOMDERROR_Marshal 

SOMDERROR_NotProcessOwner 

This error code is returned when the somdd daemon is trying to kill the server process and if the owner of the server 
process is different from that of the somdd daemon. 

SOMDERROR_Serverlnactive 

The specified server is in the process of being activated. 

SOMDERROR_ServerDisabled 

The server has been disabled by the program servmgr. 

SOMDERROR_SOMDAIreadyRunning 

The DSOM daemon has been started when another daemon is already running. 

SOMDERROR_ServerToBeDeleted 

An attempt has been made to start or connect to a server marked for deletion. 

SOMDERROR_NoObjRefTable 

The Object Reference Table cannot be found. 

SOMDERRORJJpdatelmpIDef 

The Implementation Repository cannot be updated. 




30138 SOMDERROR_NolmplDirectory 

The directory signified by SOMDDIR does not exist. 

30169 SOMDERROR_ServerNotStoppable 

An attempt has been made to stop a server (using the dsom stop command or a SOMDServerMgr object) 
registered as nonstoppable. 

XXXXX SOMDERRORjDperatingSystem 

On AIX, this is the value of the C error variable "errno" defined in errno.h; on OS/2 and Windows, it is the DOS API 
return code. 



Metaclass Framework Error Codes 



It is possible to receive the following messages from the Metaclass Framework while an application is running. 

60001 An attempt was made to construct a class with SOMMSinglelnstance as a metaclass constraint. (This may occur 
indirectly because of the construction of a derived metaclass). The initialization of the class failed because 
somlnitMICIass defined by SOMMSinglelnstance is in conflict with another metaclass that has overridden 
somNew. That is, some other metaclass has already claimed the right to return the value for somNew. 

60002 An attempt was made to construct a class with SOMMSinglelnstance as a metaclass constraint. (This may occur 
indirectly because of the construction of a derived metaclass). The initialization of the class failed because 
somlnitMICIass defined by SOMMSinglelnstance is in conflict with another metaclass that has overridden 
somFree. That is, some other metaclass has already claimed this right to override somFree. 

60004 An invocation of somrFtepInit was made with a logging type other tha 'o' or 'v'. 

60005 The sommBeforeMethod or the sommAfterMethod was invoked on a SOMRReplicableObject whose logging type 
is other than 'o' or 'v\ This error cannot occur normally. The likely cause is that some method invoked on another 
object has overwritten this object's memory. 

60006 A Before/After Metaclass must override both sommBeforeMethod and sommAfterMethod. This message indicates 
an attempt to create a Before/After Metaclass where only one of the above methods is overridden. 



SOM IDL Language Grammar 



specification 

definition 



modu/e 

interface 

interface_dci 

inheritance 

export 



scoped_name 



const_dci 



: [comment] definition + 

: type_dci ; {com men t\ 

| const_dci ; \comment\ 
j interface ; \comment\ 
j modu/e ; [comment] 
j pragma_stm 

: module identifier \comment\ 

{ \commenf\ definition + } 

: interface identifier 
| interface_dci 

: interface identifier \inheritance\ \comment\ 
{ \comment\ export * } \comment\ 

: scoped_name {, scoped_nameX 
: type_dci ; \comment\ 

| const_dci ; \commenf\ 
j attr_dci ; \comment\ 

| op_dci ; [comment] 
j imp/ementation_body ; [ comment ] 
j pragma_stm 
: identifier 
| :: identifer 

j scoped_name :: identifer 
: const const_type identifier = 




const_ expr 



co ns t_ type 


: integer_type 
| cbar_type 
| boo/ean_type 
| f/oat/ng_pt_type 
1 stringtype 
| scoped_name 


const_ expr 


: or_expr 


or_expr 


: xor_expr 
| or_expr 
j xor expr 


xor_expr 


: ar>d_ expr\xor_ expr A and_ expr 


and_ expr 


: shift_expr 

| and_expr & sb/ft_expr 


sb/ft_expr 


: add_expr 

| sb/ft_expr:epv. :pk. » add_expr 
| sb/ft_expr:epv. « add_expr 


add_expr 


: mu/t_expr 

| add_expr + mu/t_expr 
| add_expr - mu /t_ expr 


mu /t_ expr 


: ur>ary_expr 
| mu /t_ expr * ur>ary_expr 
j mu/t_expr / ur>ary_expr 
j mu /t_ expr % unary_expr 


unary_expr 


: ur>ary_operator primary_expr 
| pr/mary_expr 


ur>ary_ operator 


| + 


pr/mary_expr 


: scoped_name 
| /te/a/ 

j ( const_ expr ) 


/ tera. Z 


: integer_/itera/ 

\ string /itera/ 
j character_/itera/ 
j f/oat/ng_pt_//tera/ 
j boo/ean_//tera/ 


type_dct 


: typedef type_dec/arator 
| constr_type_spec 


type_ dec/arator 


: type_spec dec/arator {, dec/arator } 


type_spec 


: s/mp/e_type_spec 
| constr_type_spec 


s/mp/e_ type_ spec 


: base_type_spec 
| temp/ate_type_spec 
j scoped_name 


base_type_spec 


: f/oat/ng_pt_type 
| /nteger_type 
j cbar_type 
j boo/ean_type 
j octet_type 
1 ar>y_type 
j vo/dptr_type 


temp/a te_ type_ spec 


: sequence_type 
1 stringtype 


constr_ type_ spec 


: struct_type 
| union type 
j enum_type 


dec/arator 


: [■s/are] std_dec/arator 


std_dec/arator 


: s/mp/e_dec/arator 
| comp/ex_dec/arator 


stmp/e_ dec/arator 


: identifier 


comp/ex_ dec/arator 


: array_dec/arator 


array_ dec/arator 


: s/mp/e_dec/arator f/xed_array_size 


f/xed_ array_ size 


: [ const_ expr ] 


f/oat/ng_pt_ type 


: float 
| double 


/nteger_type 


: s/gned_/nt 
| uns/gned_int 


s/gned_/nt 


: long 
| short 


uns/gned_int 


: unsigned s/gned_/nt 


cf>ar_type 


: char 


boo/ean_type 


: boolean 




octet_type 
any_type 
voidptr_type 
struct_ type 



member 
unto n_ type 



sw/tch_ type_ spec 



case 

case_/abet 

e/ement_spec 

er>um_type 

sequence_type 

string_ type 

attr_dcl 

op_c/c/ 

op_type_spec 

parameter- dc/s 

param_dci 
param_ attribute 

raises_expr 
context- expr 
imp/ementation_ body 

impiementation 

pragmas tm 

modifier_stm 
modifier 
modifier- va/ue 



passthru 

smidentifier 

stars 



: octet 
: any 

: void stars 

: ( struct|exception) identifier 
| ( struct|exception) [comment] 

{ [comment] member * } 

: type_dec/arator ; \comment\ 

: union identifier 
| union identifier switch 
( s witch_ type_spac ) [ 
comment] 

{ [ comment \ case+ } 

: integer_ type 
| char_type 
j boo/ean_type 
j enum_type 
j scoped_name 

: case_/abe/+ e/ement_spac ; [ comment \ 

: case const-expr '■ [ comment ] 

| default : [ comment ] 

: type_spec dec/a ra tor 
: enum identifier { identifier 
{, identifier }* [ comment \ } 

: sequence < simp/e_type_spec , consf expr > 

| sequence < simp/e_type_spec > 

: string < const- expr > 

| string 

: [readonly] attribute simp/e_type_spec 
dec/a ra tor {, declarator}* 

: [oneway] op_type_spac [stars] identifier 
parameter_dc/s \raises_expr] \context_expr\ 

: simp/e_type_spec 
| void 

: ( param_dci {, param_dc/}* [comme nt] ) 

10 

: param_ attribute simp/e_ type_ spec declarator 

: in 
| out 
| inout 

: raises ( scope_name+ ) 

: context ( context_stahg{, context_string}* ) 

: implementation [ comment ] 

{ [ comment ] impiementation+ } 

: modifier_stm 

| pragmas tm 

j passthru 
| member 

: #pragma modifier modifier_stm 
| #pragma somtemittypes on 
j #pragma somtemittypes off 

: smidentifier : [modifier {, modifier}*] ;[ comment ] 
| modifier ; [ comment ] 

: smidentifier 

| smidentifier = modifier_value 
: smidentifier 
I string_/iterai 
j integer_/iterai 
j keyword 

: passthru identifier = string_titera/+ ; [ comment ] 
: identifer 
| -identifier 

r+ 



Implementing Sockets Subclasses 



Distributed SOM (DSOM) and the Replication Framework require basic message services for inter-process communications. The Event 




Management Framework must be integrated with the same communication services in order to handle communications events. 

To maximize their portability to a wide variety of local area network transport protocols, the DSOM, Replication, and Event Management 
Frameworks have been written to use a common commun/cat/ons interface , which is implemented by one or more SOM class libraries 
using available local protocols. 

The common communications interface is based on the "sockets" interface used with TCP/IP, since its interface and semantics are fairly 
widespread and well understood. The IDL interface is named Sockets. There is no implementation associated with the Sockets interface by 
default; specific protocol implementations are supplied by subclass implementations. 

Note: The Sockets classes supplied with the SOMobjects Developer Toolkit and run-time packages are on/y intended to support the 
DSOM, Replication, and Event Management Frameworks. These class implementations are not intended for general application 
usage . 



Available Sockets subclasses by SOMobjects product are as follows: 

For AIX: 

TCPIPSockets class for TCP/IP, 

IPXSockets class for Netware IPX/SPX, and 
NBSockets class for NetBIOS. 

■ For OS/2 and Windows: 

TCPIPSockets class (a) for TCP/IP for Windows or (b) for TCP/IP 1 .2.1 on OS/2, 

TCPIPSockets32 class for TCP/IP 2.0 on OS/2 only (see Note below), 

IPXSockets class for NetWare IPX/SPX, and 
NBSockets class for NetBIOS. 

Note: The TCPIPSocket32 class gives greater performance over the TCPIPSockets class on OS/2, but requires the 32-bit version of 
TCPP/IP (version 2.0) rather than the 16-bit version of TCP/IP (version 1.2.1). 



Application developers may need to develop their own Sockets subclass if the desired transport protocol or product version is not one of 
those supported by the SOMobjects run-time packages. This appendix explains how to approach the implementation of a Sockets subclass, 
if necessary. 

Warning: this may be a non-trivial exercise! 



Sockets IDL interface 

The base Sockets interface is expressed in IDL in the file somssock.idl, listed below. There is a one-to-one mapping between TCP/IP 
socket APIs and the methods defined in the Sockets interface. 

Please note the following: 

• The semantics of each of the Sockets methods must be that of the corresponding TCP/IP call. Currently, only Internet address 
family (AFJNET) addresses are used by the frameworks. 

(The TCP/IP sockets API is not documented as part of the SOMobjects Developer Toolkit. The implementor is referred to the 
programming references for IBM TCP/IP for AIX or OS/2, or to similar references that describe the sockets interface for TCP/IP.) 

• Data types, constants, and macros which are part of the Sockets interface are defined in a C include file, soms.h. This file is 
supplied with the SOMobjects Toolkit, and is not shown in this manual. 

• The Sockets interface is expressed in terms of a 32-bit implementation. 

• Some of the method parameters and return values are expressed using pointer types, for example: 

hostent *somsGethostent (); 



This has been done to map TCP/IP socket interfaces as directly as possible to their IDL equivalent. (Use of strict CORBA IDL 
was not a primary goal for the Sockets interface, since it is only used internally by the frameworks.) 

The Sockets class and its subclasses are single instance classes. 



Following is a listing of the file somssock.idl. Each socket call is briefly described with a comment. 



// 96F8647, 96F8648 (C) Copyright IBM Corp . 1992, 1993 
// All Rights Reserved 

// Licensed Materials - Property of IBM 

#ifndef somssock_idl 
#define somssock_idl 

#include <somobj.idl> 

#include <snglicls . idl> 

interface Sockets : SOMObject 

{ 

//# The following typedefs are fully defined in <soms.h>. 
typedef SOMFOREIGN sockaddr; 

#pragma modifier sockaddr : impctx="C" , struct; 
typedef SOMFOREIGN iovec; 

#pragma modifier iovec : impctx="C", struct; 
typedef SOMFOREIGN msghdr; 

#pragma modifier msghdr : impctx="C", struct; 
typedef SOMFOREIGN fd_set; 

#pragma modifier fd_set : impctx= n C", struct; 
typedef SOMFOREIGN timeval; 

#pragma modifier timeval : impctx= n C", struct; 
typedef SOMFOREIGN hostent; 

#pragma modifier hostent : impctx= n C", struct; 
typedef SOMFOREIGN servent; 

#pragma modifier servent : impctx= n C", struct; 
typedef SOMFOREIGN in_addr; 

#pragma modifier in_addr : impctx= n C", struct; 

long somsAccept (in long s, out sockaddr name, out long namelen) ; 
// Accept a connection request from a client. 

long somsBind (in long s, inout sockaddr name, in long namelen) ; 
// Binds a unique local name to the socket with descriptor s. 

long somsConnect (in long s, inout sockaddr name, 
in long namelen) ; 

// For streams sockets, attempts to establish a connection 
// between two sockets. For datagram sockets, specifies the 
// socket's peer. 

hostent *somsGethostbyaddr (in char *addr, in long addrlen, 

in long domain) ; 

// Returns a hostent structure for the host address specified on 
// the call. 

hostent *somsGethostbyname (in string name) ; 

// Returns a hostent structure for the host name specified on 
// the call. 

hostent *somsGethostent (); 

// Returns a pointer to the next entry in the hosts file, 
unsigned long somsGethostid (); 

// Returns the unique identifier for the current host. 

long somsGethostname (in string name, in long namelength) ; 

// Retrieves the standard host name of the local host. 

long somsGetpeername (in long s, out sockaddr name, 
out long namelen) ; 

// Gets the name of the peer connected to socket s. 

servent *somsGetservbyname (in string name, in string protocol) ; 
// Retrieves an entry from the /etc/services file using the 
// service name as a search key. 

long somsGetsockname (in long s, out sockaddr name, 
out long namelen) ; 

// Stores the current name for the socket specified by the s 
// parameter into the structure pointed to by the name 
// parameter. 




long somsGetsockopt (in long s, in long level, in long optname, 
in char *optval, out long option) ; 

// Returns the values of socket options at various protocol 
// levels. 

unsigned long somsHtonl (in unsigned long a) ; 

// Translates an unsigned long integer from host-byte order to 
// network-byte order. 

unsigned short somsHtons (in unsigned short a) ; 

// Translates an unsigned short integer from host-byte order to 
// network-byte order. 

long somsloctl (in long s, in long cmd, in char *data, 
in long length) ; 

// Controls the operating characteristics of sockets, 
unsigned long somsInet_addr (in string cp) ; 

// Interprets character strings representing numbers expressed 
// in standard ' . ' notation and returns numbers suitable for use 
// as internet addresses. 

unsigned long somsInet_lnaof (in in_addr addr) ; 

// Breaks apart the internet address and returns the local 
// network address portion. 

in_addr somsInet_makeaddr (in unsigned long net, 

in unsigned long lna) ; 

// Takes a network number and a local network address and 
// constructs an internet address. 

unsigned long somsInet_netof (in in_addr addr) ; 

// Returns the network number portion of the given internet 
// address. 

unsigned long somsInet_network (in string cp) ; 

// Interprets character strings representing numbers expressed 
// in standard ' . ' notation and returns numbers suitable for use 
// as network numbers. 

string somsInet_ntoa (in in_addr addr) ; 

// Returns a pointer to a string expressed in the dotted-decimal 
// notation. 

long somsListen (in long s, in long backlog) ; 

// Creates a connection request queue of length backlog to queue 
// incoming connection requests, and then waits for incoming 
// connection requests. 

unsigned long somsNtohl (in unsigned long a) ; 

// Translates an unsigned long integer from network-byte order 
// to host-byte order. 

unsigned short somsNtohs (in unsigned short a) ; 

// Translates an unsigned short integer from network-byte order 
// to host-byte order. 

long somsReadv (in long s, inout iovec iov, in long iovcnt) ; 

// Reads data on socket s and stores it in a set of buffers 
// described by iov. 

long somsRecv (in long s, in char *buf, in long len, 
in long flags) ; 

// Receives data on streams socket s and stores it in buf. 

long somsRecvf rom (in long s, in char *buf, in long len, 
in long flags, out sockaddr name, out long namelen) ; 

// Receives data on datagram socket s and stores it in buf. 

long somsRecvmsg (in long s, inout msghdr msg, in long flags) ; 

// Receives messages on a socket with descriptor s and stores 
// them in an array of message headers. 

long somsSelect (in long nfds, inout fd_set readfds, 

inout fd_set writefds, inout fd_set exceptfds, 
inout timeval timeout) ; 

// Monitors activity on a set of different sockets until a 




// timeout expires, to see if any sockets are ready for reading 
// or writing, or if an exceptional condition is pending. 

long somsSend (in long s, in char *msg, in long len, 
in long flags) ; 

// Sends msg on streams socket s. 

long somsSendmsg (in long s, inout msghdr msg, in long flags) ; 

// Sends messages passed in an array of message headers on a 
// socket with descriptor s. 

long somsSendto (in long s, inout char msg, in long len, 

in long flags, inout sockaddr to, in long tolen) 
// Sends msg on datagram socket s. 

long somsSetsockopt (in long s, in long level, in long optname, 
in char *optval, in long optlen) ; 

// Sets options associated with a socket. 

long somsShutdown (in long s, in long how) ; 

// Shuts down all or part of a full-duplex connection. 

long somsSocket (in long domain, in long type, 
in long protocol) ; 

// Creates an endpoint for communication and returns a socket 
// descriptor representing the endpoint. 

long somsSoclose (in long s) ; 

// Shuts down socket s and frees resources allocated to the 
// socket. 

long somsWritev (in long s, inout iovec iov, in long iovcnt) ; 

// Writes data on socket s. The data is gathered from the 
// buffers described by iov. 

attribute long serrno; 

// Used to pass error numbers. 

#if def SOMIDL 

implementation 

{ 

releaseorder : 

somsAccept, somsBind, somsConnect, somsGethostbyaddr , 
somsGethostbyname, somsGethostent , somsGethostid, 
somsGethostname, somsGetpeername, somsGetsockname, 
somsGetsockopt , somsHtonl, somsHtons, somsloctl, 
somsInet_addr , somsInet_lnaof , somsInet_makeaddr , 
somsInet_netof , somsInet_network, somsInet_ntoa, 
somsListen, somsNtohl, somsNtohs, somsReadv, 
somsRecv, somsRecvf rom, somsRecvmsg, somsSelect, 
somsSend, somsSendmsg, somsSendto, somsSetsockopt, 
somsShutdown, somsSocket, somsSoclose, somsWritev, 
_set_serrno, _get_serrno, somsGetservbyname; 

//# Class modifiers 
callstyle=idl; 

metaclass = SOMMSinglelnstance; 
ma jorversion=l ; minorversion=l ; 
dll="soms .dll" ; 



#endif /* SOMIDL */ 

} ; 

#endif /* somssock_idl */ 



IDL for a Sockets subclass 



Sockets subclasses inherit their entire interface from Sockets. All methods are overridden. 
For example, here is a listing of the TCPIPSockets IDL description. 




// 96F8647, 96F8648 (C) Copyright IBM Corp . 1992, 1993 
// All Rights Reserved 

// Licensed Materials - Property of IBM 



#ifndef tcpsock_idl 
#define tcpsock_idl 

#include <somssock . idl> 

#include <snglicls . idl> 

interface TCPIPSockets : Sockets 

{ 

#if def SOMIDL 

implementation 

{ 

//# Class modifiers 
callstyle=idl; 

ma jorversion=l ; minorversion=l ; 
dllname="somst .dll" ; 
met acl as s=SOMMS ingle Instance; 
//# Method modifiers 
somsAccept : override; 
somsBind: override; 
somsConnect : override; 
somsGethostbyaddr : override; 
somsGethostbyname : override; 
somsGethostent : override; 
somsGethostid : override; 
somsGethostname : override; 
somsGetpeername : override; 
somsGetservbyname : override; 
somsGetsockname : override; 
somsGetsockopt : override; 
somsHtonl : override; 
somsHtons : override; 
somsloctl: override; 
somsInet_addr : override; 
somsInet_lnaof : override; 
somsInet_makeaddr : override; 
somsInet_netof : override; 
somsInet_network : override; 
somsInet_ntoa : override; 
somsListen: override; 
somsNtohl : override; 
somsNtohs : override; 
somsReadv: override; 
somsRecv: override; 
somsRecvf rom : override; 
somsRecvmsg: override; 
somsSelect: override; 
somsSend: override; 
somsSendmsg: override; 
somsSendto: override; 
somsSetsockopt : override; 
somsShutdown : override; 
somsSocket: override; 
somsSoclose: override; 
somsWritev: override; 
_set_serrno: override; 
_get_serrno: override; 

} ; 

#endif /* SOMIDL */ 

} ; 

#endif /* tcpsock_idl */ 



Implementation considerations 



Only the AFJNET address family must be supported. That is, the DSOM, Replication, and Event Manager frameworks all use 




Internet addresses and port numbers to refer to specific sockets. 

On OS/2, the SOMobjects run-time libraries were built using the C Set/2 32-bit compiler. If the underlying subclass 
implementation uses a 16-bit subroutine library, conversion of the method call arguments may be required. (This mapping of 
arguments is often referred to as "thunking.") 

Sockets subclasses to be used in multi-threaded environments should be made thread-safe. That is, it is possible that 
concurrent threads may make calls on the (single) Sockets object, so data structures must be protected within critical regions, 
as appropriate. 

Valid values for the serrno attribute are defined in the file soms.h. The subclass implementation should map local error numbers 
into the appropriate corresponding Sockets error numbers. 



Example code 



The following code fragment shows an example of the implementation of the somsBind method of the TCPIPSockets subclass, for both 
AIX and OS/2. The sample illustrates that, for TCP/IP, the implementation is basically a one-to-one mapping of Sockets methods onto 
TCP/IP calls. For other transport protocols, the mapping from the socket abstraction to the protocol's API may be more difficult. 

For AIX, the mapping from Sockets method to TCP/IP call is trivial. 

SOM_Scope long SOMLINK somsBind (TCPIPSockets somSelf, 

Environment *ev, 

long s, Sockets_sockaddr* name, 

long namelen) 

{ 

long rc; 

TCPIPSocketsMethodDebug ( "TCPIPSockets" , "somsBind") ; 
rc = (long) bind((int)s, name, (int) namelen) ; 
if (rc == -1) 

set_serrno ( somSelf , ev, errno) ; 

return rc; 

} 



On OS/2, however, the TCP/IP Release 1 .2.1 library is a 16-bit library. Consequently, many of the method calls require conversion 
("thunking") of 32-bit parameters into 16-bit parameters, before the actual TCP/IP calls can be invoked. For example, the function prototype 
for the somsBind method is defined as: 

SOM_Scope long SOMLINK somsBind (TCPIPSockets somSelf, 

Environment *ev, 

long s, Sockets_sockaddr* name, 

long namelen) ; 



whereas the file socket.h on OS/2 declares the bind function with the following prototype: 

short _Farl6 _Cdecl bind (short /*s*/, void * _Segl6 /*name*/, 

short /*len*/); 



In this case, the pointer to the "name" structure, passed as a 32-bit address, cannot be used directly in the bind call: a 16-bit address must 
be passed instead. This can be accomplished by dereferencing the 32-bit pointer provided by the "name" parameter in the somsBind call, 
copying the caller's Sockets_sockaddr structure into a local structure ("name16"), and then passing the address of the local structure 
("&name16") as a 16-bit address in the bind call. 

SOM_Scope long SOMLINK somsBind (TCPIPSockets somSelf, 

Environment *ev, 

long s, Sockets_sockaddr* name, 

long namelen) 

{ 

long rc; 

Socket s_sockaddr namel6; 




TCPIPSocketsMethodDebug ("TCPIPSockets", "somsBind") ; 



/* copy user's parameter into a local structure */ 

memcpy ((char *)&namel6, (char *) ( (sockaddr32 *)name) , namelen) ; 

rc = (long) bind ( (short ) s, (void *)&namel6, (short ) namelen) ; 

if (rc == -1) 

set_serrno (somSelf , ev, tcperrno () ) ; 

return rc; 
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Glossary 



Note: In the following definitions, words shown in /ta//cs are terms for which separate glossary entries are also defined. 



abstract class 



affinity group 



ancestor class 



aggregate type 



A c/ass that is not designed to be instantiated, but serves as a base c/ass for the definition of subclasses. 
Regardless of whether an abstract class inherits instance data and methods from parent classes , it will always 
introduce methods that must be overridden in a subc/ass. in order to produce a class whose objects are 
semantically valid. 

An array of c/ass objects that were all registered with the SOMC/assMgr object during the dynamic loading of a 
class. Any class is a member of at most one affinity group. 

A class from which another class inherits instance methods, attributes, and instance variables , either directly or 
indirectly. A direct descendant of an ancestor class is called a chi/d class, derived class, or subc/ass. A direct 
ancestor of a class is called a parent c/ass, base c/ass, or superclass. 

A user-defined data type that combines basic types (such as, char, short, float, and so on) into a more complex type 
(such as structs, arrays, strings, sequences, unions, or enums). 



apply stub A procedure corresponding to a particular method that accepts as arguments: the object on which the method is to 

be invoked, a pointer to a location in memory where the method's result should be stored, a pointer to the method's 
procedure, and the method's arguments in the form of a vajist. The apply stub extracts the arguments from the 
vajist, invokes the method with its arguments, and stores its result in the specified location. Apply stubs are 
registered with class objects when instance methods are defined, and are invoked using the somApply function. 
Typically, implementations that override somDispatch call somApply to invoke a method on a vajist of arguments. 




attribute A specialized syntax for declaring "set" and "get" methods. Method names corresponding to attributes always begin 

with "_set_" or "_get_". An attribute name is declared in the body of the interface statement for a class. Method 
procedures for get/set methods are automatically defined by the SOM Compi/er unless an attribute is declared as 
"noget/noset". Likewise, a corresponding instance variab/e is automatically defined unless an attribute is declared as 
"nodata". IDL also supports "readonly" attributes, which specify only a "get" method. (Contrast an attribute with an 
instance variab/e . ) 

auxiliary class data structure: A structure provided by the SOM API to support efficient static access to c/ass- specific information used in 
dealing with SOM objects. The structure's name is <c/ass/Vame> CCIassData. Its first component (parentMtab) is a 
list of parent-c/ass method tab/es (used to support efficient parent method calls). Its second component 
(instanceDataToken) is the instance token for the class (generally used to locate the instance data introduced by 
method procedures that implement methods defined by the class). 

base class See parent c/ass. 

behavior (of an object) The methods that an object responds to. These methods are those either introduced or inherited by the c/ass of 
the object. See also state. 

bindings: Language-specific macros and procedures that make implementing and using SOM classes more convenient. These 

bindings offer a convenient interface to SOM that is tailored to a particular programming language. The SOM 
Compi/er generates binding files for C and C ++. These binding files include an impiementation temp/ate for the 
class and two header files, one to be included in the class's implementation file and the other in client programs. 

BOA (basic object adapter) class: A CORBA interface (represented as an abstract c/ass in DSOM), which defines generic object-adapter 
(OA) methods that a server can use to register itself and its objects with an ORB (object request broker) . See also 
SOMOA (SOM object adapter) c/ass. 

callback A user-provided procedure or method to the Event Management Framework that gets invoked when a registered 

event occurs. (See also event ). 

casted dispatching A form of method dispatching that uses casted method resolution-, that is, it uses a designated ancestor class of the 
actual target object's class to determine what procedure to call to execute a specified method. 

casted method resolution A method reso/ution technique that uses a method procedure from the method tab/e of an ancestor of the 
c/ass of an object (rather than using a procedure from the method table of the object's own class). 

child class A class that inherits instance methods, attributes, and instance variab/es directly from another class, called the 

parent c/ass, base c/ass, or superciass, or indirectly from an ancestor c/ass. A child class may also be called a 
derived c/ass or subc/ass. 

class A way of categorizing objects based on their behavior (the methods they support) and shape (memory layout). A 

class is a definition of a generic object. In SOM, a class is also a special kind of object that can manufacture other 
objects that all have a common shape and exhibit similar behavior. The specification of what comprises the shape 
and behavior of a set of objects is referred to as the "definition" of a class. New classes are defined in terms of 
existing classes through a technique known as inheritance. See also c/ass object. 

class variable instance data of a c/ass object. All instance data of an object is defined (through either introduction or inheritance ) 

by the object's class. Thus, class variables are defined by metac/asses . 

class data structure A structure provided by the SOM API to support efficient static access to c/ass- specific information used in dealing 
with SOM objects. The structure's name is <c/assi/ame> ClassData. Its first component (classObject) is a pointer to 
the corresponding c/ass object. The remaining components (named after the instance methods and instance 
variab/es ) are method tokens or data tokens, in order as specified by the class's implementation. Data tokens are 
only used to support data (public and private) introduced by classes declared using O/DL ; IDL attributes are 
supported with method tokens. 

class manager An object that acts as a run-time registry for all SOM class objects that exist within the current process and which 
assists in the dynamic loading and unloading of class libraries. A class implementor can define a customized class 
manager by subclassing SOMC/assMgr class to replace the SOM-supplied SOMCIassMgrObject. This is done to 
augment the functionality of the default class-management registry (for example, to coordinate the automatic 
quiescing and unloading of classes). 

class method (Also known as factory method or constructor .) A class method is a method that a c/ass object responds to (as 

opposed to an instance method). A class method that class <X> responds to is provided by the metac/ass of class 
<X>. Class methods are executed without requiring any instances of class <X> to exist, and are frequently used to 
create instances of the class. 

class object The run-time object representing a SOM c/ass. In SOM, a class object can perform the same behavior common to 

all objects, inherited from SOMObject. 

client code (Or c/ient program or c/ienti) An application program, written in the programmer's preferred language, which invokes 

methods on o bjects that are instances of SOM c/asses. In DSOM, this could be a program that invokes a method 




on a remote object. 

constructor See c/ass method . 

context expression An optional expression in a method's IDL declaration, specifying identifiers whose value (if any) can be used during 
SOM’s method reso/ut/on process and/or by the target object as it executes the method procedure . If a context 
expression is specified, then a related Context parameter is required when the method is invoked. (This Context 
parameter is an implicit parameter in the IDL specification of the method, but it is an explicit parameter of the 
method's procedure.) No SOM-supplied methods require context parameters. 

CORBA The Common Object Request Broker Architecture established by the Object Management Group. IBM's tnterface 

Definition Language used to describe the interface for SOM classes is fully compliant with CORBA standards. 

daemon See DSOM daemon . 

data token A value that identifies a specific instance variab/e within an object whose c/ass inherits the instance variable (as a 

result of being derived, directly or indirectly, from the class that introduces the instance variable). An object and a 
data token are passed to the SOM run-time procedure, somDataResolve, which returns is a pointer to the specific 
instance variable corresponding to the data token. (See also instance token. ) 

derived class See subc/ass and subc/assing. 

derived metaclass (Or SOM-derived metac/ass .) A metac/ass that SOM creates automatically (often even when the c/ass implementor 
specifies an explicit metaclass) as needed to ensure that, for any code that executes without method-resotution error 
on an instance of a given class, the code will similarly execute without method-resolution error on instances of any 
subc/ass of the given class. SOM's ability to derive such metaclasses is a fundamental necessity in order to ensure 
binary compatibility for client programs despite any subsequent changes in class imp/ementations . 

descriptor (Or method descriptor .) An ID representing the identifier of a method definition or an attribute definition in the 

Interface Repository. The IR definition contains information about the method's return type and the type of its 
arguments. 

directive A message (a pre-defined character constant) received by a rep/ica from the Replication Framework. Indicates a 

potential failure situation. 

dirty object A persistent object that has been modified since it was last written to persistent storage. 

dispatch-function resolution Dispatch-function resolution is the slowest, but most flexible, of the three method-reso/ution techniques SOM 
offers. Dispatch functions permit method resolution to be based on arbitrary rules associated with an object' s c/ass. 
Thus, a class implementor has complete freedom in determining how methods invoked on its instances are resolved. 
See also dispatch method and dynamic dispatching. 

dispatch method A method (such as somDispatch or somClassDispatch) that is invoked (and passed an argument list and the ID of 
another method) in order to determine the appropriate method procedure to execute. The use of dispatch methods 
facilitates dispatch-function resotution in SOM applications and enables method invocation on remote objects in 
DSOM applications. See also dynamic dispatching . 

DLL Abbreviation for dynamic /ink iibrary . 

DSOM daemon (somdd) The DSOM process (somdd) that locates and activates servers. The daemon (actually known as the iocation 

services daemon) is primarily meant to provide a client with the necessary communications information to allow the 
client to connect with an implementation server. 

dynamic dispatching Method dispatching using dispatch- function resolution -, the use of dynamic method resolution at run time. See also 
dispatch- function reso/ution and dynamic method. 

Dynamic Invocation Interface (Dll) The CORBA -specified interface , implemented in DSOM, that is used to dynamically build requests on 
remote objects. Note that DSOM applications can also use the somDispatch method for dynamic method calls when 
the object is remote. See also dispatch method. 

dynamic link library A piece of code that can be loaded (activated) dynamically. This code is physically separate from its callers. DLLs 
can be loaded at load time or at run time. Widely used term on OS/2, Windows, and, to some extent, AIX. 

dynamic method A method that is not declared in the IDL interface statement for a c/ass of objects , but is added to the interface at 
run time, after which instances of the class (or of its subclasses ) will respond to the registered dynamic method. 
Because dynamic methods are not declared, usage bindings for SOM classes cannot support their use; thus, offset 
method resolution is not available. Instead, name-lookup or dispatch-function method resolution must be used to 
invoke dynamic methods. (There are currently no known uses of dynamic methods by any SOM applications.) See 
also method and static method. 

encapsulation An object-oriented programming feature whereby the implementation details of a class are hidden from client 

programs, which are only required to know the interface of a c/ass (the signatures of its methods and the names of 
its attributes) in order to use the class's methods and attributes. 




encoder/decoder 



In the Persistence Framework, a c/ass that knows how to read/write the persistent object format of a persistent 
object. Every persistent object is associated with an Encoder/Decoder, and an encoder/decoder object is created for 
each attribute and instance variab/e. An Encoder/Decoder is supplied by the Persistence Framework by default, or 
an application can define its own. 

entry class In the Emitter Framework, a ciass that represents some syntactic unit of an interface definition in the /DL source fi/e. 

Environment parameter A CORBA-xe quired parameter in all method procedures , it represents a memory location where exception 
information can be returned by the object of a method invocation. [Certain methods are exempt (when the class 
contains a modifier of callstyle=oidl), to maintain upward compatibility for client programs written using an earlier 
release.] 

Generically, a program that takes the output from one system and converts the information into a different form. 

Using the Emitter Framework, selected output from the SOM Compiier (describing each syntactic unit in an /DL 
source fi/e) is transformed and formatted according to a user-defined template. Example emitter output, besides the 
implementation template and language bindings, might include reference documentation, class browser descriptions, 
or "pretty" printouts. 

The occurrence of a condition, or the beginning or ending of an activity that is of interest to an application. Examples 
are elapse of a time interval, sending or receiving of a message, and opening or closing a file. (See also event 
manager and callback) 

event manager (EMan) The chief component of the Event Management Framework that registers interest in various events from calling 
modules and informs them through ca/ibacks when those events occur. 

See c/ass method . 

See som/d. 

A user-written .idl file, expressed using the syntax of the interface Definition Language (IDL), which describes the 
interface for a particular c/ass (or classes, for a modu/e). The IDL source file is processed by the SOM Compiier to 
generate the binding fi/es specific to the programming languages of the class implementor and the client application. 
(This file may also be called the "IDL file," the "source file," or the "interface definition file.") 

(Or object implementation .) The specification of what instance variables implement an object's state and what 
procedures implement its methods (or behaviors). In DSOM, a remote object's implementation is also characterized 
by its server implementation (a program). 

Implementation Repository A database used by DSOM to store the implementation definitions of DSOM servers. 

implementation statement An optional declaration within the body of the interface definition of a class in a SOM /DL source fi/e, 

specifying information about how the class will be implemented (such as, version numbers for the class, overriding of 
inherited methods, or type of method resolution to be supported by particular methods). This statement is a 

SOM-unique statement; thus, it must be preceded by the term "#ifdef SOMIDL " and followed by "#endif". See 

also interface declaration. 

implementation template A template file containing stub procedures for methods that a c/ass introduces or overrides. The 

implementation template is one of the binding fi/es generated by the SOM Compiler when it processes the /DL 
source fi/e containing class interface dec/arations. The class implementor then customizes the implementation, by 
adding language-specific code to the method procedures . 

implicit method parameter A method parameter that is not included in the IDL interface specification of a method, but which is a 

parameter of the method's procedure and which is required when the method is invoked from a c/ient program . 
Implicit parameters include the required Environment parameter indicating where exception information can be 
returned, as well as a Context parameter, if needed. 

incremental update A revision to an implementation temp/ate file that results from reprocessing of the /DL source fi/e by the SOM 

Compi/er. The updated implementation file will contain new stub procedures , added comments, and revised method 
prototypes reflecting changes made to the method definitions in the IDL specification. Importantly, these updates do 
not disturb existing code that the class implementor has defined for the prior method procedures. 

inheritance The technique of defining one c/ass (called a subc/ass. derived c/ass, or chi/d c/ass) as incremental differences 

from another class (called the parent c/ass. base c/ass, superclass, or ancestor c/ass). From its parents, the 
subclass inherits variables and methods for its instances. The subclass can also provide additional instance 
variab/es and methods. Furthermore, the subclass can provide new procedures for implementing inherited methods. 
The subclass is then said to override the parent class's methods. An overriding method procedure can elect to call 
the parent class's method procedure . (Such a call is known as a parent method ca// .) 

inheritance hierarchy The sequential relationship from a root class to a subclass, through which the subclass inherits instance methods, 
attributes, and instance variab/es from all of its ancestors, either directly or indirectly. The root class of all SOM 
classes is SOMObject. 



factory method 
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IDL source file 
implementation 



emitter 



event 




instance 



(Or object instance or just object .) A specific object, as distinguished from a c/ass of objects. See also object. 



instance method A method valid for an object instance (as opposed to a c/ass method , which is valid for a c/ass object). An instance 
method that an object responds to is defined by its class or inherited from an ancestor class. 

instance token A data token that identifies the first instance variab/e among those introduced by a given c/ass. The 
somGetlnstanceToken method invoked on a c/ass object returns that class's instance token. 

instance variables (Or, instance data .) Variables declared for use within the method procedures of a c/ass. An instance variable is 

declared within the body of the impiementation statement in a SOM /DL source fi/e . An instance variable is "private" 
to the class and should not be accessed by a client program. (Contrast an instance variable with an attribute . ) 

interface The information that a c/ient must know to use a c/ass namely, the names of its attributes and the signatures of its 

methods . The interface is described in a formal language (the interface Definition Language , IDL) that is 
independent of the programming language used to implement the class's methods. 

interface declaration (Or interface statement. ) The statement in the /DL source fi/e that specifies the name of a new class and the names 
of its parent c/ass (es). The "body" of the interface declaration defines the signature of each new method and any 
attribute (s) associated with the class. In SOM IDL, the body may also include an impiementation statement (where 
instance variab/es are declared or a modifier is specified, for example to overrides, method). 

Interface Definition Language (IDL) The formal language (independent of any programming language) by which the interface for a c/ass 
of objects is defined in a .idl file, which the SOM Compi/er then interprets to create an impiementation temp/ate file 
and binding files. SOM's Interface Definition Language is fully compliant with standards established by the Object 
Management Group's Common Object Request Broker Architecture ( COFtBA ). 

Interface Repository (IR) The database that SOM optionally creates to provide persistent storage of objects representing the major 

elements of interface definitions. Creation and maintenance of the IR is based on information supplied in the /DL 
source fi/e. The SOM IR Framework supports all interfaces described in the COFtBA standard. 

Interface Repository Framework A set of c/asses that provide methods whereby executing programs can access the persistent objects of 
the interface Ftepository to discover everything known about the programming interfaces of SOM classes. 

IR Abbreviation for interface Repository . 

location services daemon (somdd) A process whose primary purpose is to give DSOM clients the communications information that they 
need to connect with an implementation server. 

macro An alias for executing a sequence of hidden instructions; in SOM, typically the means of executing a command 

known within a binding fi/e created by the SOM Compi/er. 

metaclass A c/ass whose instances are classes. In SOM, any class descended from SOMC/ass is a metaclass. The methods 

a class inherits from its metaclass are sometimes called c/ass methods (in Smalltalk) or factory methods (in 
Objective-C) or constructors . See also c/ass method. 

metaclass incompatibility A situation where a subc/ass does not include all of the c/ass variab/es or respond to all of the class methods 
of its ancestor c/asses . This situation can easily arise in OOP systems that allow programmers to explicitly specify 
metac/asses , but is not allowed to occur in SOM. Instead, SOM automatically prevents this by creating and using 
derived metac/asses whenever necessary. 

method A combination of a procedure and a name, such that many different procedures can be associated with the same 

name. In object-oriented programming, invoking a method on an object causes the object to execute a specific 
method procedure . The process of determining which method procedure to execute when a method is invoked on an 
object is called method resolution . (The COPBA standard uses the term "operation" for method invocation). SOM 
supports two different kinds of methods: static methods and dynamic methods. See also static method and dynamic 
method. 

method descriptor See descriptor. 

method ID A number representing a zero-terminated string by which SOM uniquely represents a method name. See also 

som/d. 

method pointer A pointer type that identifies one method procedure on a single class. Method pointers are not ensured to be 
persistent among multiple processes. 

method procedure A function or procedure, written in an arbitrary programming language, that implements a method of a c/ass. A 

method procedure is defined by the class implementor within the impiementation temp/ate file generated by the SOM 
Compi/er. 

method prototype A method declaration that includes the types of the arguments. Based on method definitions in an /DL source fi/e. 

the SOM Compi/er generates method prototypes in the implementation temp/ate . A class implementor uses the 
method prototype as a basis for writing the corresponding method procedure code. The method prototype also shows 
all arguments and their types that are required to invoke the method from a c/ient program . 




method resolution The process of selecting a particular method procedure , given a method name and an object instance. The process 
results in selecting the particular function/procedure that implements the abstract method in a way appropriate for the 
designated object. SOM supports a variety of method-resolution mechanisms, including offset method reso/ution, 
name-iookup reso/ution, and dispatch-function reso/ution . 

method table A table of pointers to the method procedures that implement the methods that an object supports. See also method 

token. 

method token A value that identifies a specific method introduced by a c/ass. A method token is used during method reso/ution to 

locate the method procedure that implements the identified method. The two basic method-resolution procedures 
are somResolve (which takes as arguments an object and a method token, and returns a pointer to a procedure that 
implements the identified method on the given object) and somClassResolve (which takes as arguments a c/ass and 
a method token, and returns a pointer to a procedure that implements the identified method on an instance of the 
given class). 

modifier Any of a set of statements that control how a c/ass, an attribute , or a method will be implemented. Modifiers can be 

defined in the impiementation statement of a SOM /DL source fi/e . The implementation statement is a SOM-unique 
extension of the CORBA specification. [User-defined modifiers can also be specified for use by user-written emitters 
or to store information in the interface Repository , which can then be accessed via methods provided by the 
interface Repository Framework .] 

module The organizational structure required within an /DL source fi/e that contains interface dec/arations for two (or more) 

classes that are not a class-metaclass pair. Such interfaces must be grouped within a module declaration. 

multiple inheritance The situation in which a ciass is derived from (and inherits interface and impiementation from) multiple parent 
classes. 

name-lookup method resolution Similar to the method reso/ution techniques employed by Objective-C and Smalltalk. It is significantly 
slower than offset reso/ution . Name-lookup resolution, unlike offset resolution, can be used when the name of the 
method to be invoked is not known until run time, or the method is added to the class interface at run time, or the 
name of the class introducing the method is not known until run time. 

naming scope: See scope. 

object (Or object instance or just instance .) An entity that has state (its data values) and behavior (its methods ). An 

object is one of the elements of data and function that programs create, manipulate, pass as arguments, and so forth. 
An object is a way to encapsulate state and behavior. Encapsu/ation permits many aspects of the impiementation of 
an object to change without affecting client programs that depend on the object's behavior. In SOM, objects are 
created by other objects called c/asses. 

object adapter (OA) A CORBA term denoting the primary interface a server impiementation uses to access ORB functions; in 

particular, it defines the mechanisms that a server uses to interact with DSOM, and vice versa. This includes server 
activation/deactivation, dispatching of methods , and authentication of the principai making a call. The basic object 
adapter described by CORBA is defined by the BOA (basic object adapter) abstract c/ass ; DSOM's primary object 
adapter implementation is provided by the SOMOA [SOM Object Adapter) c/ass. 

object definition See c/ass. 

object implementation See impiementation. 

object instance See instance and object. 

object reference A CORBA term denoting the information needed to reliably identify a particular object. This concept is implemented 
in DSOM with a proxy object in a c/ient process, or a SOMDObject in a server process. See also proxy object and 
SOMDObject. 

object request broker (ORB) See ORB. 

offset method resolution: The default mechanism for performing method reso/ution in SOM, because it is the fastest (nearly as fast as an 
ordinary procedure call). It is roughly equivalent to the C ++ "virtual function" concept. Using offset method resolution 
requires that the name of the method to be invoked must be known at compile time, the name of the c/ass that 
introduces the method must be known at compile time (although not necessarily by the programmer), and the method 
to be invoked must be a static method . 

OIDL The original language used for declaring SOM c/asses. The acronym stands for Object Interface Definition 

Language. OIDL is still supported by SOM release 2, but it does not include the ability to specify mu/tip/e inheritance 
classes. 

one-copy serializable The consistency property of the Replication Framework which states that the concurrent execution of methods on a 
rep/icated object is equivalent to the serial execution of those same methods on a nonreplicated object. 



OOP 



An acronym for "object-oriented programming.' 




operation 



See method 



operation logging In the Replication Framework, a technique for maintaining consistency among replicas of a replicated object, 
whereby the execution of a method that updates the object is repeated at the site of each replica. 

ORB (object request broker) A COFtBA term designating the means by which objects transparently make requests (that is, invoke 

methods ) and receive responses from objects, whether they are local or remote. With SOMobjects Developer Toolkit 
and Runtimes, this functionality is implemented in the DSOM Framework. Thus, the DSOM (Distributed SOM) system 
is an ORB. See also BOA (basic object adapter) c/ass and SOMOA (SOM object adapter) c/ass. 

overridden method A method defined by a parent class and reimplemented (redefined or overridden) in the current class. 

override (Or overriding method.) The technique by which a c/ass replaces (redefines) the imp/ementat/on of a method that it 

inherits from one of its parent c/asses . An overriding method can elect to call the parent class's method procedure 
as part of its own implementation. (Such a call is known as a parent method cat/ .) 

parent class A c/ass from which another class inherits instance methods , attributes , and instance variab/es. f\ parent class is 

sometimes called a base c/ass or superclass. 

parent method call A technique where an overriding method calls the method procedure of its parent c/ass as part of its own 
implementation . 

persistent object An object whose state can be preserved beyond the termination of the process that created it. Typically, such 
objects are stored in files. 

polymorphism An object-oriented programming feature that may take on different meanings in different systems. Under various 

definitions of polymorphism, (a) a method or procedure call can be executed using arguments of a variety of types, 
or (b) the same variable can assume values of different types at different times, or (c) a method name can denote 
more than one method procedure. The SOM system reflects the third definition (for example, when a SOM class 
overrides a parent c/ass definition of a method to change its behavior). The term literally means "having many 
forms.” 

principal The user on whose behalf a particular (remote) method is being performed. 

procedure A small section of code that executes a limited, well-understood task when called from another program. In SOM, a 

method procedure is often referred to as a procedure. See also method procedure. 

process A series of instructions (a program or part of a program) that a computer executes in a multitasking environment. 

proxy object In DSOM, a SOM object in the client's address space that represents a remote object. The proxy object has the 

same interface as the remote object, but each method invoked on the proxy is overridden by a dispatch method 
that forwards the invocation request to the remote object. Under DSOM, a proxy object is created dynamically and 
automatically in the client whenever a remote method returns a pointer to an object that happens to be remote. 

readers and writers In the Replication Framework, different processes can access the same replicated object in different modes. A 
"reader" is a process that does not intend to update the object, but wants to continually watch the object as other 
processes update it. A "writer" is a process that wants to update the object, as well as continually watch the updates 
performed by others. 

receiver See target object. 

redispatch stub A procedure , corresponding to a particular method , which has the same signature as the method's procedure but 

which invokes somDispatch to dispatch the method. The somOverrideMtab method can be used to replace the 
procedure pointers in a c/ass's method tab/e with the corresponding redispatch stubs. This is done when overriding 
somDispatch to customize method resolution so that all static method invocations will be routed through 
somDispatch for selection of an appropriate method procedure . [Dynamic methods have no entries in the method 
table, so they cannot be supported with redispatch functionality.) 

reference data Application-specific data that a server uses to identify or describe an object in DSOM. The data, represented by a 
sequence of up to 1024 bytes, is registered with DSOM when a server creates an object reference . A server can 
later ask DSOM to return the reference data associated with an object reference. See also object reference. 

replica When an object is replicated among a set of processes (using the Replication Framework), each process is said to 

have a replica of the object. From the view point of any application model, the replicas together represent a single 
object. 

replicated object An object for which replicas (copies) exist. See replica. 

run-time environment The data structures, objects, and global variables that are created, maintained, and used by the functions, 
procedures, and methods in the SOM run-time library. 



scope 



(Or naming scope. ) That portion of a program within which an identifier name has "visibility" and denotes a unique 




variable. In SOM, an /DL source fi/e forms a scope. An identifier can only be defined once within a scope; identifiers 
can be redefined within a nested scope. In a .idl file, modules, interface statements, structures, unions, methods, and 
exceptions form nested scopes. 

serializable See one-copy serializable . 

server (Or server implementation. ) In DSOM, a process , running in a distributed environment, that executes the 

imp/ementat/on of an object. DSOM provides a default server implementation that can dynamically load SOM c/ass 
libraries, create SOM objects, and make those objects accessible to c/ients. Developers can also write 
application-specific servers for use with DSOM. 

server object In DSOM, every server has an object that defines metboc/s for managing objects in that server. These methods 

include object creation, object destruction, and maintaining mappings between object references and the objects 
they reference. A server object must be an instance of the c/ass SOMDServer (or one of its subc/asses). See also 
object reference and SOMDObject. 

shadowing In the Emitter Framework, a technique that is required when any of the entry c/asses are subclassed. Shadowing 

causes instances of the new subclass(es) (rather than instances of the original entry classes) to be used as input for 
building the object graph, without requiring a recompile of emitter framework code. Shadowing is accomplished by 
using the macro SOM_SubstituteClass. 

signature The collection of types associated with a metboc/ (the type of its return value, if any, as well as the number, order, 

and type of each of its arguments). 

sister class object A duplicate of a c/ass object that is created in order to save a copy of the class's original metboc/ tab/e before 

replacing the method table to customize metboc/ reso/utfon. The sister class object is created so that some original 
metboc/ procec/ures can be called by the replacement method procedures. 

Sockets class A class that provides a common communications interface to Distributed SOM, the Replication Framework, and the 

Event Management Framework. The Sockets class provides the base interfaces (patterned after TCP/IP sockets); 
the subc/asses TCPIPSockets, NBSockets, and IPXSockets provide actual implementations for TCP/IP, Netbios, 
and Netware IPX/SPX, respectively. 

SOM Compiler A tool provided by the SOM Toolkit that takes as input the interface definition file for a class (the .idl file) and 
produces a set of binding fi/es that make it more convenient to implement and use SOM classes. 

SOMCIass One of the three primitive class objects of the SOM run-time environment. SOMCIass is the root (meta)class from 

which all subsequent metac/asses are derived. SOMCIass defines the essential behavior common to all SOM c/ass 
objects. 

SOMCIassMgr One of the three primitive class objects of the SOM run-time environment. During SOM initialization, a single 

instance ( object ) of SOMCIassMgr is created, called SOMCIassMgrObject. This object maintains a directory of all 
SOM classes that exist within the current process, and it assists with dynamic loading and unloading of class 
libraries. 

SOM-derived metaclass: See derived metac/ass. 

SOMDObject The c/ass that implements the notion of a CORBA "object reference" in DSOM. An instance of SOMDObject 

contains information about an object's server implementation and interface, as well as a user-supplied identifier. 

somld A pointer to a number that uniquely represents a zero-terminated string. Such pointers are declared as type somld. In 

SOM, somld's are used to represent method names, c/ass names, and so forth. 

SOMObject One of the three primitive class objects of the SOM run-time environment. SOMObject is the root class for all SOM 

(sub)classes. SOMObject defines the essential behavior common to all SOM objects. 

SOMOA (SOM object adapter) class In DSOM, a c/ass that dispatches methods on a server's objects , using the SOM Compiler and 
run-time support. The SOMOA class implements methods defined in the abstract BOA class (its base c/ass). See 
also BOA c/ass. 

somSelf Within method procedures in the implementation file for a class, a parameter pointing to the target object that is an 

instance of the c/ass being implemented, it is local to the method procedure . 

somThis Within method procedures, a local variable that points to a data structure containing the instance variables 

introduced by the class . If no instance variables are specified in the SOM /DL source fi/e, then the somThis 
assignment statement is commented out by the SOM Compiler . 

state (of an object) The data ( attributes. ; instance variables and their values) associated with an object. See also behavior. 

static method Any method that can be accessed through offset method resolution . Any method declared in the IDL specification of 

a class is a static method. See also method and dynamic method. 



stub procedures Method procedures in the implementation template generated by the SOM Compiler. They are procedures whose 




bodies are largely vacuous, to be filled in by the implementor. 



subclass 

subclassing 

superclass 

symbol 

target object 

usage bindings 
value logging 
view-data paradigm 

writers 

(No title) 



A c/ass that inherits instance methods , attributes , and instance variab/es directly from another class, called the 
parent c/ass. base c/ass, superc/ass, or indirectly from an ancestor class . A subclass may also be called a chi/d 
class or derived c/ass. 

The process whereby a new class, as it is created (or derived), inherits instance methods, attributes, and instance 
variab/es from one or more previously defined ancestor classes . The immediate parent c/assfesj of a new class 
must be specified in the class's interface declaration, see also inheritance. 

See parent class. 

In the Emitter Framework, any of a (standard or user-defined) set of names (such as, className) that are used as 
placeholders when building a text template to pattern the desired emitter output. When a template is emitted, the 
symbols are replaced with their corresponding values from the emitter's symbol table. Other symbols (such as, 
classSN) have values that are used by section-emitting methods to identify major sections of the template (which are 
correspondingly labeled as "classS" or by a user-defined name). 

(Or receiver. ) The object responding to a method call. The target object is always the first formal parameter of a 
method procedure . For SOM's C-language bindings, the target object is the first argument provided to the method 
invocation macro, _method/Vame . 

The language-specific binding files for a c/ass that are generated by the SOM Compi/er for inclusion in client 
programs using the class. 

In the Replication Framework, a technique for maintaining consistency among replicas of a replicated object, 
whereby the new value of the object is distributed after the execution of a method that updates the object. 

A Replication Framework construct similar to the Model-View-Controller paradigm in SmallTalk. The "view" object 
contains only presentation-specific information, while the "data” object contains the state of the application. The 
"view" and "data" are connected by means of an "observation" protocol that lets the "view" be notified whenever the 
"data” changes. 

See readers and writers. 



". C++ is a trademark of AT&T, Inc. 




